@enfyra/mcp-server 0.0.31 → 0.0.32

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

@@ -11,6 +11,8 @@ Use this skill when designing, reviewing, or debugging Enfyra apps through MCP w
 - 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.
@@ -19,6 +21,18 @@ Use this skill when designing, reviewing, or debugging Enfyra apps through MCP w
 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`

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)
 
@@ -204,18 +204,21 @@ The Enfyra backend is private infrastructure. MCP, browser code, SSR routes, Gra
 When an LLM builds a Nuxt, Next, or other SSR frontend for Enfyra, follow the Enfyra Cloud pattern:
 
 - 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}/**` } } }`.
+- 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=...`.
+- 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,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.31",
+  "version": "0.0.32",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",

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,12 @@ 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.',
-    '- 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}/**` } } }`. Browser/generated app code calls `/enfyra/...`, not the raw Enfyra backend URL.',
+    '- 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=<returnUrl>`**. Use token-query callback handling only when the app intentionally manages tokens itself.',
+    '- 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`.',
     '',
@@ -88,6 +90,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **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).`,
@@ -128,6 +133,18 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- 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.',
@@ -144,23 +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.',
-    '- **Cloud-style proxy mode:** generated Nuxt/Next apps should start OAuth through the same-origin proxy, e.g. `/enfyra/auth/google?redirect=...`, and let Enfyra handle the auth response. Do not generate a set-cookie route unless the user explicitly chooses a custom SSR auth boundary.',
+    '- **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):** Cloud-style apps use `GET /enfyra/auth/{provider}?redirect=<URL_ENCODED>` 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.',
+    '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 Cloud-style proxy mode, Enfyra owns the auth response behind the app proxy. 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 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)}``.',
+    '- **“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`. `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.',
@@ -226,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/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',
   [