@enfyra/mcp-server 0.0.30 → 0.0.32

package/.codex/skills/enfyra-mcp-performance/SKILL.md

@@ -0,0 +1,47 @@
+# Enfyra MCP Performance And Debug Mode
+
+Use this skill when designing, reviewing, or debugging Enfyra apps through MCP where performance, read/write shape, indexes, websocket latency, RLS filters, or query correctness matter.
+
+## Rules
+- Verify capability with live metadata before claiming performance behavior. Use `inspect_table`, `inspect_route`, `discover_query_capabilities`, and `discover_runtime_context` first.
+- Prefer indexed relation filters over scalar mirror columns. Relation property names can be used in `indexes` and `uniques`; Enfyra resolves them to physical FK columns.
+- For hot read paths, design indexes with the most selective/user-scoped field first. Examples: `["member","is_read","conversation"]` for unread lookup and `["conversation","member","is_read"]` for mark-read updates.
+- Use existence checks for UI dots and badges unless the user explicitly needs exact counts. Avoid count queries on every conversation row.
+- Use `meta=filterCount` or MCP `count_records` only when count is the product requirement.
+- For RLS hooks, mutate `@QUERY.filter` and preserve existing user filters with `_and`. `@QUERY.filter` is already `{}` when omitted.
+- For dynamic scripts, keep runtime values in their original type. Do not wrap ids or payload values in `String(...)`, `Number(...)`, or `Boolean(...)`.
+- For websocket apps, connect browsers through the Enfyra app/Nuxt bridge, not the hidden backend. Event handlers should be script-owned and use `@SOCKET` explicitly.
+- Authenticated websocket gateways load `user_definition` once and expose it as `@USER`; do not ask clients to send their own `senderId`.
+- Enfyra automatically joins authenticated sockets to `user_<userId>` after the connection script succeeds. App scripts should use this for `emitToUser` and should not re-join that room manually.
+
+## Debug Workflow
+1. Inspect the table schema, relations, indexes, and route permissions before changing code.
+2. Reproduce with the smallest real request or Socket.IO event. Prefer `test_rest_endpoint` or `run_admin_test` when available.
+3. If the problem is performance, state the exact query shape and expected index. Add or update `indexes` on `table_definition` through `create_table` or `update_table`.
+4. Reload metadata/cache after schema or script changes when the tool does not do it automatically.
+5. Retest the exact route/event and compare behavior before/after. Do not invent benchmark numbers.
+
+## Chat App Review Checklist
+- Confirm REST and Socket.IO both go through the app origin. REST uses the app proxy prefix; Socket.IO uses `/ws/<namespace>` and `path: "/ws/socket.io"` when the app bridge exposes that path.
+- Confirm browser code never stores or forwards custom JWT cookies when the Enfyra app/proxy already manages cookies.
+- Confirm `chat:join` queries `chat_conversation` visible to `@USER`, then joins `conversation:<id>`. Do not join rooms from raw membership member ids.
+- Confirm `chat:message` uses `@SOCKET.broadcastToRoom("conversation:" + conversationId, ...)` and persists with `@REPOS` inside the event script. Do not add a flow just to save chat messages.
+- Confirm new DM UX creates no empty conversation. A draft opens first; the first message calls a creation event that creates the conversation and message together.
+- Confirm route-level RLS is server-side: pre-hooks merge membership filters into `@QUERY.filter` with `_and`; the client must not fetch all conversations then filter locally.
+- Confirm conversation titles are computed from visible memberships from the current user's perspective. DM title should be the other person, not the current user.
+- Confirm message history uses cursor pagination, newest messages first from the API then reversed for display; loading older messages preserves scroll.
+- Confirm disconnect state disables chat input and shows a visible retry banner immediately.
+- Confirm typing state is room-scoped, user-aware, and remains active while the input has text, even if the user pauses typing.
+
+## Chat Read/Unread Pattern
+- Use a join table, e.g. `chat_message_read`, with:
+  - `message` relation to `chat_message`
+  - `conversation` relation to `chat_conversation`
+  - `member` relation to `user_definition`
+  - `is_read` boolean
+  - `read_at` date nullable
+- Add unique `["message","member"]`.
+- Add indexes `["member","is_read","conversation"]` and `["conversation","member","is_read"]`.
+- On message create, create read rows for conversation members. Sender rows start as read; other member rows start unread.
+- On conversation open/read, update unread rows for `@USER` in that conversation to read.
+- UI unread dots should check whether an unread row exists; count only when requested.

package/README.md

@@ -3,7 +3,7 @@
 MCP server for managing Enfyra instances from **Codex**, **Claude Code**, **Cursor**, and other MCP-compatible clients. All operations go through Enfyra's REST API.
 
 
-**LLM rules (REST, GraphQL, auth, URL, mutation `create_{tableName}`, etc.):** not in this README — see **`src/lib/mcp-instructions.js`** (content sent via MCP `instructions`) and tool descriptions in **`src/index.mjs`**. This README only covers **MCP installation and configuration** for users/devs.
+**LLM rules (REST, GraphQL, auth, URL, mutation `create_{tableName}`, etc.):** not in this README — see **`src/lib/mcp-instructions.js`** (content sent via MCP `instructions`), **`src/lib/mcp-examples.js`** (concrete examples loaded through `get_enfyra_examples`), and tool descriptions in **`src/index.mjs`**. This README only covers **MCP installation and configuration** for users/devs.
 
 **Official docs:** [Claude Code MCP](https://docs.anthropic.com/en/docs/claude-code/mcp) · [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings) · [Cursor MCP (`mcp.json`)](https://cursor.com/docs/context/mcp)
 
@@ -201,18 +201,24 @@ The Enfyra backend is private infrastructure. MCP, browser code, SSR routes, Gra
 
 ### SSR app auth pattern
 
-When an LLM builds a Nuxt, Next, or other SSR frontend for Enfyra, use a same-origin proxy:
+When an LLM builds a Nuxt, Next, or other SSR frontend for Enfyra, follow the Enfyra Cloud pattern:
 
-- Browser code calls `{{ appOrigin }}/api/**`, never the raw Enfyra backend URL.
-- Cookie-managed password login is `POST {{ appOrigin }}/api/login`, not `/api/auth/login`. The SSR route calls backend `/auth/login` and stores Enfyra `accessToken`, `refreshToken`, and `expTime` as httpOnly cookies.
-- Cookie-managed OAuth should enable Enfyra OAuth cookie handling (`autoSetCookies` / set-cookies mode). Start OAuth at `{{ appOrigin }}/api/auth/:provider?redirect=...`; Enfyra redirects to `{{ appOrigin }}/api/auth/set-cookies`, then the SSR route sets cookies and redirects to the requested page.
+- Browser code calls a same-origin proxy such as `{{ appOrigin }}/enfyra/**`, never the raw Enfyra backend URL.
+- Nuxt can proxy it with `routeRules: { "/enfyra/**": { proxy: { to: `${API_URL}/**`, fetchOptions: { redirect: "manual" } } } }`. Keep redirects manual so OAuth set-cookie redirects reach the browser as real HTTP redirects with `Set-Cookie`.
+- Generated apps should not create custom login/logout/me routes that manually set `accessToken`, `refreshToken`, or `expTime` cookies when the proxy is enough.
+- Password login is `POST /enfyra/login`, not `/enfyra/auth/login`.
+- Fetch the current user with `GET /enfyra/me` and logout with `POST /enfyra/logout`.
+- OAuth starts through the same proxy prefix, for example `/enfyra/auth/google?redirect=<absoluteReturnUrl>&cookieBridgePrefix=/enfyra`. `redirect` must include the app origin, and `cookieBridgePrefix` is the same proxy prefix that reaches Enfyra API routes. Enfyra validates the redirect, exchanges OAuth on its callback, then redirects through `{redirect.origin}{cookieBridgePrefix}/auth/set-cookies` so the third app origin stores the cookies before returning to `redirect`.
+- Socket.IO browser clients use a same-origin bridge too. Connect to the namespace, e.g. `io("/chat", { path: "/socket.io", withCredentials: true })`, and proxy `/socket.io/**` to the Enfyra app bridge `/ws/socket.io/**`. The backend gateway metadata path remains `/chat`.
 - Use token-query OAuth callback pages only for non-SSR/manual-token apps.
 
 ---
 
 ## Tools (summary)
 
-Metadata, query/CRUD, route/handler/hook, tables/columns, reload cache, logs, user/roles, login, menu/extension, `get_enfyra_api_context`. For full tool list and behavior, see the app after enabling MCP or the source in `src/index.mjs`.
+Metadata, examples, query/CRUD, route/handler/hook, tables/columns, reload cache, logs, user/roles, login, menu/extension, `get_enfyra_api_context`. For full tool list and behavior, see the app after enabling MCP or the source in `src/mcp-server-entry.mjs`.
+
+Use `get_enfyra_examples` when asking an LLM to generate concrete Enfyra implementation patterns. It returns categorized examples for SSR app auth/OAuth/proxy setup, schema/relations, queries/deep, handlers/hooks, permissions/RLS, websocket, flows, files, and extensions.
 
 ## Security
 

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",
   "main": "src/index.mjs",
   "bin": "src/index.mjs",
   "files": [
-    "src"
+    "src",
+    ".codex/skills"
   ],
   "scripts": {
     "start": "node src/index.mjs",

package/src/lib/mcp-examples.js

@@ -0,0 +1,581 @@
+export const EXAMPLE_CATEGORIES = {
+  'ssr-app-auth': {
+    title: 'SSR app auth, OAuth, refresh, and proxy setup',
+    useWhen: 'Use when building Nuxt, Next, or another browser app that should rely on Enfyra cookies through an app-origin proxy.',
+    examples: [
+      {
+        name: 'Nuxt routeRules for REST and Socket.IO',
+        code: `export default defineNuxtConfig({
+  routeRules: {
+    "/enfyra/**": {
+      proxy: {
+        to: \`\${process.env.ENFYRA_API_URL}/**\`,
+        fetchOptions: { redirect: "manual" }
+      }
+    },
+    "/socket.io/**": {
+      proxy: \`\${process.env.ENFYRA_APP_URL}/ws/socket.io/**\`
+    }
+  }
+})`,
+        notes: [
+          'Browser code calls /enfyra/login, /enfyra/me, /enfyra/logout, and /enfyra/<table>.',
+          'Keep redirects manual so OAuth set-cookie redirects reach the browser.',
+          'Do not add custom token cookies when the proxy is enough.',
+        ],
+      },
+      {
+        name: 'Next rewrites for REST and Socket.IO',
+        code: `const nextConfig = {
+  async rewrites() {
+    return [
+      {
+        source: "/enfyra/:path*",
+        destination: \`\${process.env.ENFYRA_API_URL}/:path*\`
+      },
+      {
+        source: "/socket.io/",
+        destination: \`\${process.env.ENFYRA_APP_URL}/ws/socket.io/\`
+      }
+    ]
+  }
+}
+
+export default nextConfig`,
+        notes: [
+          'Use rewrites for browser traffic.',
+          'If you add Next middleware/proxy for auth gating, server-side checks may call the Enfyra API origin directly while forwarding the incoming Cookie header.',
+        ],
+      },
+      {
+        name: 'Password login and current user fetch',
+        code: `await fetch("/enfyra/login", {
+  method: "POST",
+  credentials: "include",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ email, password, remember: true })
+})
+
+const me = await fetch("/enfyra/me", {
+  credentials: "include"
+}).then((res) => res.ok ? res.json() : null)`,
+        notes: [
+          'Use /login, not /auth/login, for app/browser cookie login.',
+          'Do not read or store JWTs in browser JavaScript in proxy-cookie mode.',
+        ],
+      },
+      {
+        name: 'Google OAuth button',
+        code: `const redirect = new URL("/chat", window.location.origin)
+const url = new URL("/enfyra/auth/google", window.location.origin)
+url.searchParams.set("redirect", redirect.toString())
+url.searchParams.set("cookieBridgePrefix", "/enfyra")
+window.location.href = url.toString()`,
+        notes: [
+          'redirect must be absolute and must include the app origin.',
+          'cookieBridgePrefix is the app proxy prefix that forwards to Enfyra API routes.',
+          'Enfyra redirects through {redirect.origin}{cookieBridgePrefix}/auth/set-cookies before returning to redirect.',
+        ],
+      },
+    ],
+  },
+  'schema-relations': {
+    title: 'Tables, columns, relations, cascade, and indexes',
+    useWhen: 'Use when creating or changing persisted data models.',
+    examples: [
+      {
+        name: 'Create a chat conversation table',
+        code: `create_table({
+  name: "chat_conversation",
+  columns: JSON.stringify([
+    { name: "kind", type: "varchar", isNullable: false, defaultValue: "dm" },
+    { name: "title", type: "varchar", isNullable: true },
+    { name: "last_message_text", type: "text", isNullable: true },
+    { name: "last_message_at", type: "datetime", isNullable: true }
+  ])
+})`,
+        notes: [
+          'create_table creates the default route for /chat_conversation.',
+          'Do not create tables just to get custom paths; use create_route for that.',
+        ],
+      },
+      {
+        name: 'Create relations directly to user_definition',
+        code: `create_table({
+  name: "chat_message",
+  columns: JSON.stringify([
+    { name: "text", type: "text", isNullable: false },
+    { name: "persist_status", type: "varchar", defaultValue: "persisted" }
+  ]),
+  relations: JSON.stringify([
+    {
+      propertyName: "conversation",
+      type: "many-to-one",
+      targetTable: { id: "<chat_conversation_id>" },
+      isNullable: false,
+      onDelete: "CASCADE"
+    },
+    {
+      propertyName: "sender",
+      type: "many-to-one",
+      targetTable: { id: "<user_definition_id>" },
+      isNullable: false,
+      onDelete: "CASCADE"
+    }
+  ]),
+  indexes: JSON.stringify([
+    ["conversation", "createdAt"],
+    ["sender", "createdAt"]
+  ])
+})`,
+        notes: [
+          'Use user_definition as the user table.',
+          'Do not add inverse relations on user_definition unless the user explicitly asks.',
+          'Do not provide physical FK column names; Enfyra derives them.',
+        ],
+      },
+      {
+        name: 'Unread/read table with unique and indexes',
+        code: `create_table({
+  name: "chat_message_read",
+  columns: JSON.stringify([
+    { name: "is_read", type: "boolean", defaultValue: false },
+    { name: "read_at", type: "datetime", isNullable: true }
+  ]),
+  relations: JSON.stringify([
+    { propertyName: "message", type: "many-to-one", targetTable: { id: "<chat_message_id>" }, onDelete: "CASCADE" },
+    { propertyName: "conversation", type: "many-to-one", targetTable: { id: "<chat_conversation_id>" }, onDelete: "CASCADE" },
+    { propertyName: "member", type: "many-to-one", targetTable: { id: "<user_definition_id>" }, onDelete: "CASCADE" }
+  ]),
+  uniques: JSON.stringify([["message", "member"]]),
+  indexes: JSON.stringify([
+    ["member", "is_read", "conversation"],
+    ["conversation", "member", "is_read"]
+  ])
+})`,
+        notes: [
+          'Unread is per user and per message; do not put global read state on conversation.',
+          'For chat-list UX, default to a boolean unread dot instead of exact counts.',
+        ],
+      },
+    ],
+  },
+  '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.',
+    examples: [
+      {
+        name: 'List current user conversations through membership',
+        code: `GET /enfyra/chat_conversation_member?filter={
+  "member": { "id": { "_eq": "<currentUserId>" } }
+}&deep={
+  "conversation": { "fields": "id,kind,title,last_message_text,last_message_at" }
+}&limit=0`,
+        notes: [
+          'Use relation property names in filter and deep.',
+          'limit=0 means load all matching rows.',
+          'Do not fetch messages for every conversation on initial list load; load messages after selecting a conversation.',
+        ],
+      },
+      {
+        name: 'Fetch one record by id',
+        code: `GET /enfyra/post?filter={"id":{"_eq":123}}&limit=1`,
+        notes: [
+          'There is no dynamic GET /<table>/<id> route.',
+          'Use filter + limit=1 or MCP find_one_record.',
+        ],
+      },
+      {
+        name: 'Count without loading all rows',
+        code: `GET /enfyra/chat_message_read?fields=id&limit=1&meta=filterCount&filter={
+  "member": { "id": { "_eq": "<currentUserId>" } },
+  "is_read": { "_eq": false }
+}`,
+        notes: [
+          'Use meta=totalCount with no filter and meta=filterCount with a filter.',
+          'Do not fetch all rows only to count them.',
+        ],
+      },
+      {
+        name: 'Deep relation query',
+        code: `GET /enfyra/order?fields=id,total,customer&deep={
+  "customer": { "fields": "id,email,displayName" },
+  "items": {
+    "fields": "id,quantity,product",
+    "limit": 20,
+    "deep": {
+      "product": { "fields": "id,name,price" }
+    }
+  }
+}`,
+        notes: [
+          'deep keys must be relation property names.',
+          'Allowed deep options are fields, filter, sort, limit, page, and deep.',
+          'Do not invent deep keys like members unless members is a relation on that table.',
+        ],
+      },
+    ],
+  },
+  'handlers-hooks': {
+    title: 'Custom handlers, pre-hooks, post-hooks, and script macros',
+    useWhen: 'Use when writing Enfyra dynamic JavaScript for REST behavior.',
+    examples: [
+      {
+        name: 'Custom register handler',
+        code: `const email = @BODY.email
+const password = @BODY.password
+
+if (!email || !password) @THROW400("Email and password are required")
+
+const existing = await #user_definition.find({
+  filter: { email: { _eq: email } },
+  limit: 1
+})
+if (existing.data[0]) @THROW409("Email is already registered")
+
+const result = await #user_definition.create({
+  data: {
+    email,
+    password: await @HELPERS.$bcrypt.hash(password)
+  }
+})
+
+return result.data?.[0] ?? null`,
+        notes: [
+          'create/update return { data: [...] }, not a bare row.',
+          'Use @THROW helpers for HTTP errors.',
+          'Prefer macros over raw $ctx when a macro exists.',
+        ],
+      },
+      {
+        name: 'Pre-hook RLS filter merge',
+        code: `const incoming = @QUERY.filter || {}
+const scope = {
+  memberships: {
+    member: { id: { _eq: @USER.id } }
+  }
+}
+
+@QUERY.filter = Object.keys(incoming).length
+  ? { _and: [incoming, scope] }
+  : scope`,
+        notes: [
+          '@QUERY.filter is initialized as an object for REST pre-hooks.',
+          'Mutate @QUERY.filter before canonical CRUD runs.',
+        ],
+      },
+      {
+        name: 'Post-hook response shaping',
+        code: `if (@ERROR) {
+  @LOGS("Request failed", @ERROR.message)
+  return
+}
+
+const row = Array.isArray(@DATA?.data) ? @DATA.data[0] : @DATA
+if (row) {
+  row.displayTitle = row.title || row.email || String(row.id)
+}
+
+return @DATA`,
+        notes: [
+          'Post-hooks run after success and error paths.',
+          'Return non-undefined only when replacing the response body.',
+        ],
+      },
+    ],
+  },
+  'permissions-rls': {
+    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: 'Publish read-only route',
+        code: `update_record({
+  tableName: "route_definition",
+  id: "<route_id>",
+  data: {
+    publishedMethods: [{ id: 1 }]
+  }
+})`,
+        notes: [
+          'Method id 1 is GET. Use method_definition if you need to confirm method ids.',
+          'publishedMethods controls anonymous route access. Route permissions are not for public access.',
+          'Route permissions apply when the method is not public.',
+        ],
+      },
+      {
+        name: 'Column rule for email format',
+        code: `create_column_rule({
+  tableName: "user_definition",
+  columnName: "email",
+  ruleType: "format",
+  ruleConfig: JSON.stringify({ format: "email" }),
+  message: "Please enter a valid email address"
+})`,
+        notes: [
+          'Column rules validate canonical POST/PATCH body payloads.',
+          'Use column rules before writing custom validation code when the rule is simple.',
+        ],
+      },
+      {
+        name: 'Field permission condition',
+        code: `create_field_permission({
+  tableName: "project",
+  fieldName: "internal_notes",
+  action: "read",
+  condition: JSON.stringify({
+    owner: { id: { _eq: "@USER.id" } }
+  })
+})`,
+        notes: [
+          'Field permissions are for field-level access.',
+          'Use route/pre-hook filters for row-level access.',
+        ],
+      },
+    ],
+  },
+  websocket: {
+    title: 'Socket.IO gateways, events, rooms, and browser connection',
+    useWhen: 'Use when creating realtime features.',
+    examples: [
+      {
+        name: 'Browser client connection through app bridge',
+        code: `import { io } from "socket.io-client"
+
+const socket = io("/chat", {
+  path: "/socket.io",
+  withCredentials: true,
+  transports: ["polling", "websocket"]
+})`,
+        notes: [
+          '/chat is the Socket.IO namespace.',
+          '/socket.io is the app-origin transport path proxied to Enfyra app /ws/socket.io.',
+          'Do not connect browser code directly to the hidden backend.',
+        ],
+      },
+      {
+        name: 'Connection script joins user presence room',
+        code: `if (!@USER?.id) {
+  @SOCKET.disconnect()
+  return
+}
+
+@SOCKET.join(\`user_\${@USER.id}\`)
+@SOCKET.reply("chat:ready", { userId: @USER.id })`,
+        notes: [
+          'Authenticated Enfyra sockets already load @USER.',
+          'Enfyra also joins user_<userId> for emitToUser delivery after connection succeeds.',
+        ],
+      },
+      {
+        name: 'Chat join event',
+        code: `const conversationId = @BODY.conversationId
+if (!conversationId) @THROW400("conversationId is required")
+
+const membership = await #chat_conversation_member.find({
+  filter: {
+    conversation: { id: { _eq: conversationId } },
+    member: { id: { _eq: @USER.id } }
+  },
+  limit: 1
+})
+
+if (!membership.data[0]) @THROW403("Not a conversation member")
+
+@SOCKET.join(\`conversation:\${conversationId}\`)
+@SOCKET.reply("chat:joined", { conversationId })`,
+        notes: [
+          'Join conversation rooms, not member-id rooms.',
+          'Check membership server-side; do not trust the client.',
+        ],
+      },
+      {
+        name: 'Chat message event with room broadcast and persistence',
+        code: `const { conversationId, text, clientId } = @BODY
+if (!conversationId || !text) @THROW400("conversationId and text are required")
+
+const membership = await #chat_conversation_member.find({
+  filter: {
+    conversation: { id: { _eq: conversationId } },
+    member: { id: { _eq: @USER.id } }
+  },
+  limit: 1
+})
+if (!membership.data[0]) @THROW403("Not a conversation member")
+
+const created = await #chat_message.create({
+  data: {
+    conversation: { id: conversationId },
+    sender: { id: @USER.id },
+    text,
+    persist_status: "persisted"
+  }
+})
+
+const message = created.data?.[0] ?? null
+@SOCKET.emitToRoom(\`conversation:\${conversationId}\`, "chat:message", {
+  clientId,
+  message
+})
+
+return { ok: true, message }`,
+        notes: [
+          'Do not ask the client for senderId; use @USER.id.',
+          'Event scripts should explicitly emit replies/broadcasts.',
+        ],
+      },
+    ],
+  },
+  flows: {
+    title: 'Flows and step scripts',
+    useWhen: 'Use when automating background work or chaining steps.',
+    examples: [
+      {
+        name: 'Manual flow trigger from a post-hook',
+        code: `if (!@ERROR && @DATA?.data?.[0]) {
+  await @TRIGGER("send-welcome-email", {
+    userId: @DATA.data[0].id,
+    email: @DATA.data[0].email
+  })
+}`,
+        notes: [
+          'Use flows for workflow semantics, retries, and history.',
+          'Do not use a flow just to persist a normal chat message.',
+        ],
+      },
+      {
+        name: 'Flow condition step',
+        code: `const order = @FLOW_PAYLOAD.order
+return order && order.total > 1000`,
+        notes: [
+          'Condition steps use JavaScript truthy/falsy.',
+          'Children run according to branch true/false.',
+        ],
+      },
+      {
+        name: 'Flow query step config',
+        code: `{
+  "table": "user_definition",
+  "filter": { "email": { "_contains": "@example.com" } },
+  "limit": 50
+}`,
+        notes: [
+          'Step configs are JSON; script steps use code strings.',
+          'Use public-safe URLs for HTTP steps.',
+        ],
+      },
+    ],
+  },
+  files: {
+    title: 'Files, folders, upload metadata, and assets',
+    useWhen: 'Use when handling uploads or returning uploaded files.',
+    examples: [
+      {
+        name: 'Upload a file from browser',
+        code: `const form = new FormData()
+form.append("file", file)
+form.append("folder", folderId)
+form.append("title", "Invoice")
+
+const uploaded = await fetch("/enfyra/files/upload", {
+  method: "POST",
+  credentials: "include",
+  body: form
+}).then((res) => res.json())`,
+        notes: [
+          'Do not set Content-Type manually for FormData.',
+          'Use file routes/helpers instead of writing binary data into normal tables.',
+        ],
+      },
+      {
+        name: 'Use uploaded file in handler',
+        code: `const file = $ctx.$uploadedFile
+if (!file) @THROW400("File is required")
+
+return {
+  filename: file.originalname,
+  mimetype: file.mimetype,
+  size: file.size
+}`,
+        notes: [
+          'Use file-specific context only in upload-capable routes.',
+        ],
+      },
+    ],
+  },
+  extensions: {
+    title: 'Dynamic app extensions and menus',
+    useWhen: 'Use when adding custom UI pages to the Enfyra app.',
+    examples: [
+      {
+        name: 'Create menu then extension',
+        code: `create_menu({
+  title: "Reports",
+  path: "/reports",
+  icon: "i-lucide-bar-chart-3",
+  order: 20
+})
+
+create_extension({
+  name: "ReportsPage",
+  route: "/reports",
+  component: "<template><div>Reports</div></template>"
+})`,
+        notes: [
+          'Menu provides navigation; extension provides content.',
+          'Extensions are Vue SFC records.',
+        ],
+      },
+      {
+        name: 'Extension fetches Enfyra data',
+        code: `<script setup>
+const { data, pending, refresh } = await useApi('/order_definition', {
+  query: {
+    limit: 10,
+    sort: '-createdAt'
+  }
+})
+</script>
+
+<template>
+  <UButton :loading="pending" @click="refresh">Refresh</UButton>
+  <pre>{{ data }}</pre>
+</template>`,
+        notes: [
+          'Use app-provided composables in extensions.',
+          'Keep extension UI focused; move backend logic into handlers/hooks when needed.',
+        ],
+      },
+    ],
+  },
+};
+
+export function listExampleCategories() {
+  return Object.entries(EXAMPLE_CATEGORIES).map(([key, value]) => ({
+    key,
+    title: value.title,
+    useWhen: value.useWhen,
+  }));
+}
+
+export function getExamples(category) {
+  if (!category) {
+    return {
+      categories: listExampleCategories(),
+      hint: 'Call get_enfyra_examples with one category key to retrieve concrete examples for that area.',
+    };
+  }
+
+  const entry = EXAMPLE_CATEGORIES[category];
+  if (!entry) {
+    return {
+      error: `Unknown example category "${category}"`,
+      categories: listExampleCategories(),
+    };
+  }
+
+  return {
+    category,
+    ...entry,
+  };
+}

package/src/lib/mcp-instructions.js

@@ -33,6 +33,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- If the question depends on DB type, primary key convention, cache/reload/runtime state, active GraphQL/flow/websocket/storage counts, or admin surfaces, call **`discover_runtime_context`**.',
     '- If the question depends on filters, sorting, deep relations, relation property names, field permissions, or table-specific query examples, call **`discover_query_capabilities`**; pass `tableName` when known.',
     '- If writing or reviewing handler/hook/flow/websocket/extension logic, call **`discover_script_contexts`** first so macros and `$ctx` fields are not mixed across runtime surfaces.',
+    '- If generating concrete code, schema payloads, SSR app config, OAuth wiring, Socket.IO clients/events, flows, files, extensions, or permission/RLS examples, call **`get_enfyra_examples`** for the matching category before writing the final answer. Examples are grouped by category and are intentionally more concrete than these global rules.',
     '- Treat hardcoded instructions as operating rules, but use live discovery as the final check for this running instance. Do not infer missing capabilities from a narrow tool schema; check metadata/routes or the relevant specialized tool first.',
     '- If there is no dedicated MCP tool for a subsystem, use the route-backed metadata table with `query_table` / `create_record` / `update_record` / `delete_record`, after confirming that table has a route. If the table is no-route, use the canonical specialized tool or parent table workflow instead.',
     '',
@@ -56,11 +57,13 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### When the user asks how to connect a Nuxt/Next/SSR app to Enfyra',
     '- This is guidance for the assistant to answer users and generate app code. It is not a separate MCP tool workflow.',
-    '- For real user-facing SSR apps, proxy all Enfyra traffic through the SSR app origin: **`{{ nuxtApp }}/api/**`** (or the equivalent Next route handler prefix). Browser code should call same-origin `/api/...`, not the raw Enfyra backend URL.',
-    '- If the SSR app lets Enfyra manage httpOnly cookies, password login is **`POST {{ nuxtApp }}/api/login`**, not `{{ nuxtApp }}/api/auth/login`. The SSR route calls backend `/auth/login`, stores `accessToken`, `refreshToken`, and `expTime` cookies, and returns the backend login response.',
-    '- After cookie-managed login, browser fetches use `/api/<resource>` with normal credentials/cookies; the SSR proxy/middleware attaches or refreshes the Bearer token server-side. Do not read JWTs in browser JavaScript for this mode.',
-    '- For OAuth in SSR/cookie mode, enable cookie handling on the Enfyra OAuth config (`autoSetCookies` / set-cookies mode). Start OAuth at `{{ nuxtApp }}/api/auth/{provider}?redirect=<returnUrl>`. The proxy forwards to backend `/auth/{provider}` with the app origin, backend redirects to `{{ nuxtApp }}/api/auth/set-cookies`, the SSR route stores cookies, then redirects to `redirect`.',
-    '- Token-query OAuth (`appCallbackUrl` receives `accessToken`, `refreshToken`, `expTime`) is only for non-SSR or manually managed token apps. Do not recommend it for Nuxt/Next SSR when Enfyra can set cookies.',
+    '- Follow the Enfyra Cloud app pattern by default: expose one same-origin proxy prefix such as **`/enfyra/**`** and route it to the hidden Enfyra API base, e.g. Nuxt `routeRules: { "/enfyra/**": { proxy: { to: `${API_URL}/**`, fetchOptions: { redirect: "manual" } } } }`. Browser/generated app code calls `/enfyra/...`, not the raw Enfyra backend URL. Keep redirects manual so OAuth set-cookie redirects reach the browser with their `Set-Cookie` headers.',
+    '- Do **not** generate custom login/logout/me server routes that manually set `accessToken`, `refreshToken`, or `expTime` cookies when a Cloud-style proxy is enough. Let the proxied Enfyra API own its auth response and cookies.',
+    '- Password login in generated Cloud-style Nuxt code is **`POST /enfyra/login`**, not `/enfyra/auth/login` and not a custom SSR `/api/login` wrapper.',
+    '- Fetch the current user with **`GET /enfyra/me`** and logout with **`POST /enfyra/logout`**. Browser fetches stay same-origin and credentials/cookies flow through the proxy. Do not read JWTs in browser JavaScript for this mode.',
+    '- OAuth starts on the same proxy prefix, e.g. **`GET /enfyra/auth/{provider}?redirect=<absoluteReturnUrl>&cookieBridgePrefix=/enfyra`**. `redirect` must be an absolute `http(s)` URL with the app origin. `cookieBridgePrefix` is the third app proxy prefix that forwards to the Enfyra API; Enfyra normalizes it, so `enfyra`, `/enfyra`, and `/enfyra/` all mean `/enfyra`. Use token-query callback handling only when the app intentionally manages tokens itself.',
+    '- Socket.IO uses the app bridge too. Browser clients should connect to the gateway namespace with the Socket.IO transport path on the app origin, e.g. `io("/chat", { path: "/socket.io", withCredentials: true })`, while Nuxt proxies `/socket.io/**` to the Enfyra app bridge `/ws/socket.io/**`. Do not connect browser code directly to the hidden backend Socket.IO endpoint.',
+    '- If a project explicitly standardizes on `/api/**` instead of `/enfyra/**`, keep the same Cloud-style behavior under that prefix: proxy to the Enfyra API and avoid generated cookie-management routes unless the user asks for a custom auth boundary.',
     '- If you are explaining MCP\'s own internal authentication, that is separate: this MCP server logs itself in with email/password against `{ENFYRA_API_URL}/auth/login`; for normal app work, `ENFYRA_API_URL` must still be the app proxy base such as `{{ nuxtApp }}/api`.',
     '',
     '### Routes vs tables (custom endpoints, handlers, hooks)',
@@ -75,15 +78,21 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '### After a new table is created',
     '- 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","is_read","conversation"],["conversation","member","is_read"]]` and `uniques: [["message","member"]]`. Relation property names are allowed; Enfyra resolves them to physical FK columns for SQL and Mongo.',
     '- 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`.',
     '- When modeling features that involve users, relate domain tables directly to `user_definition` through real Enfyra relations. Examples: `chat_conversation_member.member` → `user_definition`, `chat_message.sender` → `user_definition`, `order.customer` → `user_definition`. Do not create duplicate scalar columns like `userId` or separate profile records just to point back to a user.',
+    '- **Do not create reverse relations on `user_definition` by default.** For domain records that point to users, create only the owning relation on the domain table, e.g. `chat_message.sender -> user_definition`, and omit `inversePropertyName` unless the user explicitly asks for a reverse user field. Reverse fields like `user_definition.chatMessages`, `user_definition.orders`, or `user_definition.memberships` bloat user metadata and make `fields=*` user queries heavy.',
     '- **Prefer real relations over relation-shaped columns.** If a field represents another record or list of records, model it as `relations`, not as columns such as `userId`, `author_id`, `categoryIds`, `teamIds`, `itemsJson`, or object/array JSON containing related records. Ask only when the user explicitly wants denormalized snapshot data.',
     '- Common mapping: one owner record → `many-to-one`; one record has many children → define the child `many-to-one` and use inverse/read deep relation; peer/tag lists → `many-to-many`; one profile/settings row per parent → `one-to-one` when supported by the model.',
     '- If the user asks to add a foreign key field, interpret it as a relation request unless they explicitly say they need a plain scalar column. Do not create both a relation and a duplicate scalar FK column for the same concept.',
     '- **Never ask for or provide physical FK column names** when creating/updating relations. Do not include `fkCol`, `fkColumn`, `foreignKeyColumn`, `sourceColumn`, `targetColumn`, `junctionSourceColumn`, or `junctionTargetColumn` in create/update payloads unless you are only displaying existing metadata. Enfyra relation cascade derives physical FK/junction names from `propertyName` and table metadata, then hides FK columns from app form/schema definition.',
     '- For relation CRUD payloads, the public interface is the relation `propertyName`: example create body uses `"author": {"id": 1}`, not `"authorId"` or a physical FK column. Query/deep/filter keys also use relation `propertyName`.',
+    '- **Realtime/chat unread modeling:** unread/read is per user and per message. Do not put `read` or `lastRead` on `chat_conversation` globally. Prefer a join table such as `chat_message_read` with relations `message`, `conversation`, `member`, boolean `is_read`, nullable `read_at`, unique `["message","member"]`, and indexes `["member","is_read","conversation"]` plus `["conversation","member","is_read"]`. The UI can render a dot by checking existence of unread rows instead of counting every unread message.',
+    '- **Chat deletion modeling:** user-level delete/leave should remove the user from `chat_conversation_member` or otherwise make membership inactive. Do not add duplicated `deleted_at` state to both conversation and membership unless the product explicitly needs restore/audit behavior. A DM deleted for both sides is a membership operation for both members; a group is physically deleted only when no memberships remain.',
+    '- **Chat conversation title:** for DMs, compute the display title from the other visible member on the server/script response when possible. Do not trust the client to rename a DM from the current user perspective. Group titles can be generated from member display names until the product adds a custom group name.',
+    '- **Chat unread UI:** default to a boolean unread dot. Do not show unread counts unless the user explicitly asks for exact counts; exact counts require more query work and are not the default chat-list UX.',
     '- Enfyra creates a **default** route at `/{table_name}` using the table **name** from `create_table` (not the alias). Prefer **`create_route`** for additional or custom paths instead of new tables.',
     '- **Four REST HTTP operations** on that resource:',
     `  - **GET** \`${getList}\` — list / filter (query: filter, sort, page, limit, fields, meta).`,
@@ -119,10 +128,23 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### Dynamic script syntax preference',
     '- When writing server-side Enfyra scripts, prefer template macros over raw `$ctx` access: use `@BODY`, `@QUERY`, `@PARAMS`, `@USER`, `@REPOS`, `@HELPERS`, `@SOCKET`, `@TRIGGER`, `@DATA`, `@ERROR`, and `@THROW400`–`@THROW503`.',
+    '- Do not coerce dynamic script values with `String(...)`, `Number(...)`, or `Boolean(...)`. Enfyra payloads, user ids, record ids, and relation ids should keep their runtime type; validate required values and pass them through directly.',
     '- Use raw `$ctx` only when there is no template macro for the field or helper you need.',
     '- Preferred: `const result = await @REPOS.main.create({ data: @BODY });`.',
     '- Avoid: `const result = await $ctx.$repos.main.create({ data: $ctx.$body });` unless the script truly needs an unmapped `$ctx` property.',
     '',
+    '### Chat / realtime app rules learned from implementation review',
+    '- Before generating a chat app, inspect live metadata for `websocket_definition`, `websocket_event_definition`, `chat_conversation`, `chat_conversation_member`, and `chat_message`. Do not assume table names, reverse relations, route permissions, or physical field casing.',
+    '- For browser SSR apps, REST goes through the app proxy prefix and Socket.IO goes through an app-origin Socket.IO transport proxy. Third apps should connect to the namespace, e.g. `io("/chat", { path: "/socket.io", withCredentials: true })`, and proxy `/socket.io/**` to the Enfyra app bridge `/ws/socket.io/**`. Do not connect app browser code directly to the hidden backend. Do not add custom token cookies when the Enfyra app/proxy already owns cookies.',
+    '- On an authenticated gateway, Enfyra loads `user_definition` once for the socket and event scripts receive `@USER`. The server also joins `user_<userId>` after the connection script succeeds. Event scripts should not ask the client to send `senderId`, and `chat:join` does not need to join `user_<userId>` again.',
+    '- Use `chat:join` only for conversation rooms. Query `chat_conversation` with the current user membership and join `conversation:<conversationId>` rooms. Do not query all membership rows and accidentally join rooms named from member ids.',
+    '- `chat:message` should broadcast to `conversation:<conversationId>` with `@SOCKET.broadcastToRoom`, then persist through `@REPOS` in the same event script. Do not trigger a flow just to save a chat message unless the product needs workflow semantics.',
+    '- For new DMs, do not create an empty conversation just because the user selected a person. Navigate to a draft chat; create the conversation only when the first message is sent. If a DM already exists and is visible to the current user, navigate to it.',
+    '- RLS for conversation lists belongs in a route pre-hook that merges into `@QUERY.filter` with `_and`; `@QUERY.filter` already defaults to `{}`. The membership filter must target the conversation membership relation, not a duplicated scalar user id.',
+    '- Use cursor pagination for chat history. Initial load should fetch the newest messages and scroll down once; loading older messages must preserve scroll position and must not auto-scroll on new messages while the user is reading older history.',
+    '- Typing state should be room-scoped and user-aware. Broadcast typing payloads with `@USER` identity through the conversation room, keep typing active while the input still has text, and clear it only when the input is empty or the socket disconnects.',
+    '- If realtime disconnects, disable send controls immediately and show a prominent retry banner. The retry action can reload the page so REST state, socket rooms, and cookies all rehydrate from one known path.',
+    '',
     '### `$cache` / `@CACHE` user cache',
     '- `$ctx.$cache` and the `@CACHE` macro use Enfyra-managed **user cache**, not the internal runtime metadata cache.',
     '- Script keys are logical keys such as `user:123` or `report:daily`. Do not include `NODE_NAME`, `user_cache:`, Redis prefixes, or another app namespace in script code.',
@@ -139,21 +161,23 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Enfyra exposes OAuth callback at **`{ENFYRA_API_URL}/auth/{provider}/callback`**. Example when `ENFYRA_API_URL` is `http://localhost:3000/api`: **Google** callback URL is **`http://localhost:3000/api/auth/google/callback`** — i.e. `{ENFYRA_API_URL}/auth/google/callback` (same pattern for Facebook/GitHub: `.../auth/facebook/callback`, `.../auth/github/callback`).',
     '- **Google Cloud Console** → OAuth client → **Authorized redirect URIs**: register **exactly** that URL (scheme + host + path, no typo, no extra slash).',
     '- **Enfyra** (`oauth_config_definition` / OAuth settings): field **`redirectUri`** must be the **same string** as in Google Console — byte-for-byte. If they differ, Google or the server will reject the flow.',
-    '- **SSR/cookie mode:** enable `autoSetCookies` / set-cookies mode in Enfyra OAuth config. Enfyra redirects to the SSR app endpoint `/api/auth/set-cookies`, which stores httpOnly cookies and then redirects to the original `redirect` URL.',
+    '- **Cloud-style proxy mode:** generated Nuxt/Next apps should start OAuth through the same-origin proxy, e.g. `/enfyra/auth/google?redirect=<absoluteReturnUrl>&cookieBridgePrefix=/enfyra`, and let Enfyra handle the auth response. Do not generate a set-cookie route unless the user explicitly chooses a custom SSR auth boundary.',
     '- **Manual token mode only:** `appCallbackUrl` is the frontend URL where Enfyra redirects after OAuth with `accessToken`, `refreshToken`, etc. in query. Use this only when the app intentionally manages tokens itself; it is not the preferred Nuxt/Next SSR pattern.',
     '',
     '**Server flow (for answering users or designing FE):**',
-    '1. **Start login (redirect user in browser):** SSR/cookie apps use `GET {{ nuxtApp }}/api/auth/{provider}?redirect=<URL_ENCODED>`; direct/manual apps may use `GET {base}/auth/{provider}?redirect=<URL_ENCODED>`. `redirect` is required and is where to send the user after the whole flow.',
+    '1. **Start login (redirect user in browser):** Cloud-style apps use `GET /enfyra/auth/{provider}?redirect=<URL_ENCODED_ABSOLUTE_RETURN_URL>&cookieBridgePrefix=/enfyra` from the app origin; direct/manual apps may use `GET {base}/auth/{provider}?redirect=<URL_ENCODED>`. `redirect` is required and is where to send the user after the whole flow.',
     '2. Server **302** to Google/Facebook/GitHub authorization page.',
     '3. Provider calls back: `GET {base}/auth/{provider}/callback?code=...&state=...` (server exchanges code, creates/links user, issues JWT).',
-    '4. In SSR/cookie mode, backend redirects to `{{ nuxtApp }}/api/auth/set-cookies` with token query params; the SSR route stores httpOnly cookies and redirects to `redirect`. In manual token mode, backend redirects to `appCallbackUrl` with token query params. On failure, redirect includes `?error=...`.',
+    '4. In Cloud-style proxy mode, Enfyra redirects to `{redirect.origin}{cookieBridgePrefix}/auth/set-cookies?...&redirect=<originalRedirect>`. That request goes through the third app proxy to Enfyra, Enfyra returns `Set-Cookie`, then the browser is redirected to the original `redirect`. In manual token mode, backend redirects to `appCallbackUrl` with token query params. On failure, redirect includes `?error=...`.',
     '',
     '**Frontend build checklist:**',
-    '- Nuxt/Next SSR: implement same-origin API proxy at `/api/**`, a password login route at `/api/login`, and OAuth set-cookie route at `/api/auth/set-cookies`. Browser code never stores JWTs.',
-    '- **“Login with Google” button in SSR/cookie apps:** `location.href = `/api/auth/google?redirect=${encodeURIComponent(returnUrl)}``.',
+    '- Nuxt/Next generated apps: implement a same-origin API proxy such as `/enfyra/**` to the Enfyra API. Browser code never stores JWTs.',
+    '- **Password login:** `$fetch("/enfyra/login", { method: "POST", body })`.',
+    '- **Fetch user/logout:** `$fetch("/enfyra/me")` and `$fetch("/enfyra/logout", { method: "POST" })`.',
+    '- **“Login with Google” button:** `location.href = `/enfyra/auth/google?redirect=${encodeURIComponent(returnUrl)}&cookieBridgePrefix=${encodeURIComponent("/enfyra")}``, where `returnUrl` is absolute, e.g. `${location.origin}/chat`.',
     '- Manual token apps only: register `appCallbackUrl`, read token query params there, strip the URL, store tokens, and use `Authorization: Bearer`.',
     '- **Error handling:** If redirected with `?error=`, show message to user.',
-    '- **Do not confuse:** Google’s **Authorized redirect URI** = Enfyra **`redirectUri`** = backend/proxy `{API_BASE}/auth/google/callback`. SSR set-cookie route = app-owned `/api/auth/set-cookies`. `appCallbackUrl` is only for manual token mode.',
+    '- **Do not confuse:** Google’s **Authorized redirect URI** = Enfyra **`redirectUri`** = backend/proxy `{API_BASE}/auth/google/callback`. The app return URL is `redirect`, and the third-app proxy prefix is `cookieBridgePrefix`. `appCallbackUrl` is only for manual token mode.',
     '',
     '### System tables — which have REST routes',
     '- **Not all system tables have a REST route.** `query_table`, `find_one_record`, `create_record`, etc. all go through the dynamic REST API and will return **404** if the table has no registered route.',
@@ -219,7 +243,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '-   In **HTTP** handler/hook context: `reply`, `join`, `leave`, `disconnect` are not available (no socket). Use `emitToUser`, `emitToRoom`, `emitToGateway`, `broadcast`.',
     '- **Context**: Connection — `@BODY` = {id, ip, headers}, `@USER` if auth. Event — `@BODY` = payload, `@USER` if auth. Both have `@SOCKET`.',
     '- **ACK + results (recommended UX):** client can emit an event with Socket.IO ack callback. Server immediately acks `{ queued: true, requestId, eventName }` (or `{ queued: false, error }`). The handler result is returned asynchronously via `ws:result` or `ws:error` with the same `requestId`.',
-    '- **Client**: Browser apps must connect through the app/Nuxt Socket.IO bridge, not the hidden Enfyra backend. For the Enfyra Nuxt bridge this is typically `io("/ws/<namespace>")`, e.g. `io("/ws/chat")`, while the backend gateway metadata path remains `/chat`.',
+    '- **Client**: Browser apps must connect through the app/Nuxt Socket.IO bridge, not the hidden Enfyra backend. The backend gateway metadata path is the namespace, e.g. `/chat`. A third app should connect with `io("/chat", { path: "/socket.io", withCredentials: true })` and proxy `/socket.io/**` to the Enfyra app bridge `/ws/socket.io/**`. Direct Enfyra app clients may connect with `io("/ws/chat", { path: "/ws/socket.io", withCredentials: true })` when using the built-in bridge convention.',
     '- **Workflow**: Create gateway → `create_record` on `websocket_definition`. Create event → `create_record` on `websocket_event_definition` with `gateway: {id}`. Changes auto-reload; test handlers before saving.',
     '- **Test WS handler (recommended):** `POST {base}/admin/test/run` with `{ kind:"websocket_event", gatewayPath, eventName, timeoutMs, payload, script }` to run a websocket event script without a real client. Returns `{ success, result, logs, emitted }`.',
     '- MCP wrapper: use **`run_admin_test`** with `kind:"websocket_event"` or `kind:"websocket_connection"` instead of hand-building the HTTP call.',

package/src/lib/table-tools.js

@@ -42,6 +42,16 @@ function parseJsonArrayParam(name, value) {
   return parsed;
 }
 
+function normalizeConstraintGroups(name, groups) {
+  return groups.map((group, index) => {
+    const value = Array.isArray(group) ? group : group?.value;
+    if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string' || !item.trim())) {
+      throw new Error(`${name}[${index}] must be a non-empty string array or { "value": [...] }.`);
+    }
+    return value;
+  });
+}
+
 function normalizeRelationForTablePatch(relation) {
   const {
     sourceTable,
@@ -102,6 +112,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       'Create a new table definition with an auto-included `id` primary key column.',
       '**Not** for adding a custom API path or handler only — for that use **`create_route`** with an existing `mainTableId`. Use **`create_table`** when the user needs new stored data (new entity).',
       'PREFERRED: pass `columns` and `relations` params as JSON arrays to create a table WITH columns and relations in one call (cascade). Only use create_column/create_relation separately when adding to an existing table later.',
+      'Indexes and uniques are first-class table metadata. Use `indexes` for query performance and `uniques` for data integrity. Each entry is a logical field group such as [["member","is_read","conversation"]] or [{"value":["message","member"]}]. Relation property names are allowed; Enfyra resolves them to physical FK columns.',
       'Relations are supported in this same create_table call when the target table already exists. Each relation uses { targetTable, type, propertyName, inversePropertyName?, mappedBy?, isNullable?, onDelete? }; targetTable may be a table id or {id}.',
       'Do NOT provide physical FK/junction columns. Never include fkCol, fkColumn, foreignKeyColumn, sourceColumn, targetColumn, junctionSourceColumn, or junctionTargetColumn. Enfyra derives and hides those physical columns from relation propertyName/table metadata.',
       'Schema operations (create/update/delete table, add column) must run one at a time — migration locks DB; parallel calls will fail.',
@@ -119,13 +130,19 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       isSingleRecord: z.boolean().optional().describe('Set to true for single-record tables such as settings/config. This is passed directly to table_definition create.'),
       columns: z.string().optional().describe('JSON array of column definitions to create with the table (cascade). Each column: { name, type, isNullable?, isUnique?, defaultValue?, description?, options? }. The `id` column is always auto-included. Example: [{"name":"title","type":"varchar"},{"name":"status","type":"enum","options":["draft","published"]}]'),
       relations: z.string().optional().describe('JSON array of relation definitions to create with the table in the same cascade call. Each relation: { targetTable, type, propertyName, inversePropertyName?, mappedBy?, isNullable?, onDelete?, description? }. targetTable can be an id or {"id": <id>}. Do not include physical FK/junction columns such as fkCol, foreignKeyColumn, sourceColumn, targetColumn, junctionSourceColumn, or junctionTargetColumn; Enfyra derives them and hides FK columns from app schema. Example: [{"targetTable":2,"type":"many-to-one","propertyName":"author","inversePropertyName":"posts","isNullable":false,"onDelete":"CASCADE"}]'),
+      indexes: z.string().optional().describe('JSON array of logical index field groups. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Relation property names are allowed. Example: [["member","is_read","conversation"],["conversation","member","is_read"]]'),
+      uniques: z.string().optional().describe('JSON array of logical unique field groups. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Example: [["message","member"]]'),
     },
-    async ({ name, description, isSingleRecord, columns: columnsJson, relations: relationsJson }) => {
+    async ({ name, description, isSingleRecord, columns: columnsJson, relations: relationsJson, indexes: indexesJson, uniques: uniquesJson }) => {
       const idColumn = { name: 'id', type: 'int', isPrimary: true, isGenerated: true, isNullable: false };
       const userColumns = parseJsonArrayParam('columns', columnsJson);
       const userRelations = parseJsonArrayParam('relations', relationsJson).map(normalizeRelationForTablePatch);
+      const indexes = normalizeConstraintGroups('indexes', parseJsonArrayParam('indexes', indexesJson));
+      const uniques = normalizeConstraintGroups('uniques', parseJsonArrayParam('uniques', uniquesJson));
       const body = { name, description, columns: [idColumn, ...userColumns], relations: userRelations };
       if (isSingleRecord !== undefined) body.isSingleRecord = isSingleRecord;
+      if (indexesJson !== undefined) body.indexes = indexes;
+      if (uniquesJson !== undefined) body.uniques = uniques;
       const result = await fetchAPI(ENFYRA_API_URL, '/table_definition', {
         method: 'POST',
         body: JSON.stringify(body),
@@ -144,8 +161,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       const relHint = userRelations.length
         ? `Relation(s) created in same call: ${userRelations.length}.`
         : `No relations were included in this create_table call.`;
+      const constraintHint = [
+        indexes.length ? `Index group(s): ${indexes.length}.` : null,
+        uniques.length ? `Unique group(s): ${uniques.length}.` : null,
+      ].filter(Boolean).join(' ');
       return {
-        content: [{ type: 'text', text: `${colHint}\n${relHint}\n${restHint}\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
+        content: [{ type: 'text', text: `${colHint}\n${relHint}${constraintHint ? `\n${constraintHint}` : ''}\n${restHint}\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
       };
     }
   );
@@ -155,8 +176,9 @@ export function registerTableTools(server, ENFYRA_API_URL) {
   server.tool(
     'update_table',
     [
-      'Update table properties: name (rename), alias, description, isSingleRecord, graphqlEnabled.',
+      'Update table properties: name (rename), alias, description, isSingleRecord, graphqlEnabled, indexes, and uniques.',
       'Does NOT modify columns or relations — use create_column, update_column, delete_column, create_relation for those.',
+      'When passing `indexes` or `uniques`, pass the complete desired array of logical field groups; omitted fields are preserved. Relation property names are allowed and are resolved by Enfyra. Example indexes: [["member","is_read","conversation"],["conversation","member","is_read"]].',
       'Run schema changes sequentially — migration locks DB per operation.',
     ].join(' '),
     {
@@ -166,19 +188,20 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       description: z.string().optional().describe('New description.'),
       isSingleRecord: z.boolean().optional().describe('Set to true for single-record table (e.g., settings/config).'),
       graphqlEnabled: z.boolean().optional().describe('Enable or disable GraphQL for this table by syncing gql_definition.isEnabled. GraphQL still requires Bearer auth.'),
+      indexes: z.string().optional().describe('Complete JSON array of logical index field groups to store on table_definition.indexes. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Omit to preserve current indexes; pass [] to clear.'),
+      uniques: z.string().optional().describe('Complete JSON array of logical unique field groups to store on table_definition.uniques. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Omit to preserve current uniques; pass [] to clear.'),
     },
-    async ({ tableId, name, alias, description, isSingleRecord, graphqlEnabled }) => {
+    async ({ tableId, name, alias, description, isSingleRecord, graphqlEnabled, indexes: indexesJson, uniques: uniquesJson }) => {
       const body = {};
       if (name !== undefined) body.name = name;
       if (alias !== undefined) body.alias = alias;
       if (description !== undefined) body.description = description;
       if (isSingleRecord !== undefined) body.isSingleRecord = isSingleRecord;
       if (graphqlEnabled !== undefined) body.graphqlEnabled = graphqlEnabled;
+      if (indexesJson !== undefined) body.indexes = normalizeConstraintGroups('indexes', parseJsonArrayParam('indexes', indexesJson));
+      if (uniquesJson !== undefined) body.uniques = normalizeConstraintGroups('uniques', parseJsonArrayParam('uniques', uniquesJson));
 
-      const result = await fetchAPI(ENFYRA_API_URL, `/table_definition/${tableId}`, {
-        method: 'PATCH',
-        body: JSON.stringify(body),
-      });
+      const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, body);
       return {
         content: [{ type: 'text', text: `Table ${tableId} updated.\n\n${JSON.stringify(result, null, 2)}` }],
       };

package/src/mcp-server-entry.mjs

@@ -18,6 +18,7 @@ const ENFYRA_PASSWORD = process.env.ENFYRA_PASSWORD || '';
 import { login, refreshAccessToken, getValidToken, resetTokens, getTokenExpiry, initAuth } from './lib/auth.js';
 import { fetchAPI, validateFilter, validateTableName } from './lib/fetch.js';
 import { buildMcpServerInstructions, buildGraphqlUrls } from './lib/mcp-instructions.js';
+import { getExamples, listExampleCategories } from './lib/mcp-examples.js';
 import { registerTableTools } from './lib/table-tools.js';
 
 // Initialize auth module
@@ -302,6 +303,21 @@ server.tool('get_table_metadata', 'Get metadata for a specific table by name', {
   return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
 });
 
+server.tool(
+  'get_enfyra_examples',
+  [
+    'Return concrete Enfyra examples by category.',
+    'Use this before generating schemas, queries, handlers/hooks, SSR app auth, OAuth, Socket.IO, flows, files, or extensions so implementation details follow proven patterns.',
+  ].join(' '),
+  {
+    category: z.enum(listExampleCategories().map((item) => item.key)).optional().describe('Example category key. Omit to list categories.'),
+  },
+  async ({ category }) => {
+    const result = getExamples(category);
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  },
+);
+
 server.tool(
   'discover_enfyra_system',
   [
@@ -591,6 +607,8 @@ server.tool(
         preHook: {
           runs: 'Before handler.',
           data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REPOS', '@CACHE', '@HELPERS', '@THROW*', '@SOCKET emit helpers'],
+          queryContract: '@QUERY.filter is initialized as an object. When adding RLS or tenant filters in pre-hooks, merge directly with _and; do not add defensive type checks around @QUERY.filter.',
+          rlsPattern: 'For relation-scoped reads, mutate @QUERY.filter instead of returning data. Example: const incomingFilter = @QUERY.filter; const scope = { memberships: { member: { id: { _eq: @USER.id } } } }; @QUERY.filter = Object.keys(incomingFilter).length ? { _and: [incomingFilter, scope] } : scope;',
           returnBehavior: 'Returning a non-undefined value skips handler and becomes response data.',
         },
         handler: {