@enfyra/mcp-server 0.0.32 → 0.0.33

package/package.json

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

package/src/lib/mcp-examples.js

@@ -90,12 +90,12 @@ window.location.href = url.toString()`,
   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 }
+    { name: "description", type: "text", isNullable: true }
   ])
 })`,
         notes: [
           'create_table creates the default route for /chat_conversation.',
+          'Keep the latest message as a relation named lastMessage after chat_message exists; do not duplicate last message text/date columns.',
           'Do not create tables just to get custom paths; use create_route for that.',
         ],
       },
@@ -105,7 +105,7 @@ window.location.href = url.toString()`,
   name: "chat_message",
   columns: JSON.stringify([
     { name: "text", type: "text", isNullable: false },
-    { name: "persist_status", type: "varchar", defaultValue: "persisted" }
+    { name: "persistStatus", type: "varchar", defaultValue: "persisted" }
   ]),
   relations: JSON.stringify([
     {
@@ -134,13 +134,39 @@ window.location.href = url.toString()`,
           'Do not provide physical FK column names; Enfyra derives them.',
         ],
       },
+      {
+        name: 'Add chat_conversation.lastMessage after chat_message exists',
+        code: `update_table({
+  tableId: "<chat_conversation_id>",
+  relations: JSON.stringify([
+    {
+      propertyName: "createdBy",
+      type: "many-to-one",
+      targetTable: { id: "<user_definition_id>" },
+      isNullable: true,
+      onDelete: "CASCADE"
+    },
+    {
+      propertyName: "lastMessage",
+      type: "many-to-one",
+      targetTable: { id: "<chat_message_id>" },
+      isNullable: true,
+      onDelete: "SET NULL"
+    }
+  ])
+})`,
+        notes: [
+          'Use relation fields such as lastMessage.id,lastMessage.text,lastMessage.createdAt when loading conversation lists.',
+          'When deleting the current last message, a post-hook should set lastMessage to the newest remaining message or null.',
+        ],
+      },
       {
         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 }
+    { name: "isRead", type: "boolean", defaultValue: false },
+    { name: "readAt", type: "datetime", isNullable: true }
   ]),
   relations: JSON.stringify([
     { propertyName: "message", type: "many-to-one", targetTable: { id: "<chat_message_id>" }, onDelete: "CASCADE" },
@@ -149,8 +175,8 @@ window.location.href = url.toString()`,
   ]),
   uniques: JSON.stringify([["message", "member"]]),
   indexes: JSON.stringify([
-    ["member", "is_read", "conversation"],
-    ["conversation", "member", "is_read"]
+    ["member", "isRead", "conversation"],
+    ["conversation", "member", "isRead"]
   ])
 })`,
         notes: [
@@ -165,15 +191,12 @@ window.location.href = url.toString()`,
     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`,
+        name: 'List current user conversations through RLS',
+        code: `GET /enfyra/chat_conversation?fields=id,kind,title,lastMessage.id,lastMessage.text,lastMessage.createdAt&limit=0`,
         notes: [
-          'Use relation property names in filter and deep.',
-          'limit=0 means load all matching rows.',
+          'Use a conversation read pre-hook/RLS boundary so the route only returns conversations visible to @USER.',
+          'lastMessage is a relation to chat_message; do not duplicate preview fields on chat_conversation.',
+          'limit=0 means load all matching conversation rows.',
           'Do not fetch messages for every conversation on initial list load; load messages after selecting a conversation.',
         ],
       },
@@ -189,7 +212,7 @@ window.location.href = url.toString()`,
         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 }
+  "isRead": { "_eq": false }
 }`,
         notes: [
           'Use meta=totalCount with no filter and meta=filterCount with a filter.',
@@ -372,7 +395,7 @@ const socket = io("/chat", {
         code: `const conversationId = @BODY.conversationId
 if (!conversationId) @THROW400("conversationId is required")
 
-const membership = await #chat_conversation_member.find({
+const membership = await @REPOS.chat_conversation_member.find({
   filter: {
     conversation: { id: { _eq: conversationId } },
     member: { id: { _eq: @USER.id } }
@@ -394,7 +417,7 @@ if (!membership.data[0]) @THROW403("Not a conversation member")
         code: `const { conversationId, text, clientId } = @BODY
 if (!conversationId || !text) @THROW400("conversationId and text are required")
 
-const membership = await #chat_conversation_member.find({
+const membership = await @REPOS.chat_conversation_member.find({
   filter: {
     conversation: { id: { _eq: conversationId } },
     member: { id: { _eq: @USER.id } }
@@ -403,16 +426,22 @@ const membership = await #chat_conversation_member.find({
 })
 if (!membership.data[0]) @THROW403("Not a conversation member")
 
-const created = await #chat_message.create({
+const created = await @REPOS.chat_message.create({
   data: {
     conversation: { id: conversationId },
     sender: { id: @USER.id },
     text,
-    persist_status: "persisted"
+    persistStatus: "persisted"
   }
 })
 
 const message = created.data?.[0] ?? null
+if (message?.id) {
+  await @REPOS.chat_conversation.update({
+    id: conversationId,
+    data: { lastMessage: { id: message.id }, updatedAt: message.createdAt || new Date().toISOString() }
+  })
+}
 @SOCKET.emitToRoom(\`conversation:\${conversationId}\`, "chat:message", {
   clientId,
   message
@@ -510,42 +539,95 @@ return {
       {
         name: 'Create menu then extension',
         code: `create_menu({
-  title: "Reports",
+  label: "Reports",
+  type: "Menu",
   path: "/reports",
-  icon: "i-lucide-bar-chart-3",
-  order: 20
+  icon: "lucide:bar-chart-3",
+  order: 20,
+  isEnabled: true
 })
 
+// Read the created menu id from the tool response, then:
 create_extension({
+  type: "page",
   name: "ReportsPage",
-  route: "/reports",
-  component: "<template><div>Reports</div></template>"
+  description: "Reports dashboard",
+  menuId: "<created-menu-id>",
+  code: "<template><section class=\\"min-h-full w-full p-4 sm:p-6 lg:p-8\\">Reports</section></template><script setup>useHeaderActionRegistry({ id: 'refresh-reports', label: 'Refresh', icon: 'lucide:refresh-cw', onClick: () => {}, order: 0 })</script>",
+  isEnabled: true
 })`,
         notes: [
           'Menu provides navigation; extension provides content.',
-          'Extensions are Vue SFC records.',
+          'Use menu_definition.label, not title.',
+          'For page extensions, create the menu first and pass menuId to create_extension.',
+          'Page extensions should be full-bleed by default and responsive from the first version.',
+        ],
+      },
+      {
+        name: 'Plan a Cloud admin dashboard as multiple pages',
+        code: `// Recommended menu shape for an operations surface:
+create_menu({
+  type: "Dropdown Menu",
+  label: "Cloud",
+  path: "/cloud",
+  icon: "lucide:cloud",
+  order: 2,
+  isEnabled: true
+})
+
+// Child page extensions should be focused:
+// /dashboard            overview with time range KPIs
+// /cloud/projects      project status and drill-downs
+// /cloud/provisioning  provisioning timeline/failures/slow steps
+// /cloud/billing       orders/subscriptions/refunds
+// /cloud/infrastructure hosts/capacity/plans/system credential readiness
+// /cloud/readiness     legal/Paddle/landing launch checklist
+// Use UTabs inside large pages instead of placing every section in one dashboard.`,
+        notes: [
+          'Design the menu/page split before generating dashboard code.',
+          'Keep /dashboard as overview and use focused pages for operational domains.',
+          'UTabs is available in eApp extension runtime for page-level sections.',
         ],
       },
       {
         name: 'Extension fetches Enfyra data',
         code: `<script setup>
-const { data, pending, refresh } = await useApi('/order_definition', {
+const { data, pending, execute: fetchOrders } = useApi('/order_definition', {
   query: {
     limit: 10,
     sort: '-createdAt'
   }
 })
+
+onMounted(() => fetchOrders())
 </script>
 
 <template>
-  <UButton :loading="pending" @click="refresh">Refresh</UButton>
+  <UButton :loading="pending" @click="fetchOrders">Refresh</UButton>
   <pre>{{ data }}</pre>
 </template>`,
         notes: [
           'Use app-provided composables in extensions.',
+          'useApi does not auto-run; call execute() on mounted or through an action.',
           'Keep extension UI focused; move backend logic into handlers/hooks when needed.',
         ],
       },
+      {
+        name: 'Extension can use modern browser APIs',
+        code: `<script setup lang="ts">
+const statuses = ['active', 'ready']
+const ok = statuses.includes('active')
+const requiredTerms = new Set(['cloud-terms', 'privacy-policy', 'refund-policy'])
+const loaded = await Promise.all([Promise.resolve(1), Promise.resolve(2)])
+const label = String('pending_payment').replace(/_/g, ' ')
+const date = new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric' }).format(new Date())
+console.log(ok, requiredTerms.has('cloud-terms'), loaded, label, date)
+</script>`,
+        notes: [
+          'Do not rewrite extension code to ES5 when tooling rejects modern APIs.',
+          'If diagnostics complain about these APIs, fix eApp extension TypeScript lib/runtime contract.',
+        ],
+      },
     ],
   },
 };

package/src/lib/mcp-instructions.js

@@ -78,7 +78,7 @@ 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` 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","isRead","conversation"],["conversation","member","isRead"]]` 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`.',
@@ -89,7 +89,8 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- 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.',
+    '- **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 `isRead`, nullable `readAt`, unique `["message","member"]`, and indexes `["member","isRead","conversation"]` plus `["conversation","member","isRead"]`. The UI can render a dot by checking existence of unread rows instead of counting every unread message.',
+    '- **Realtime/chat latest message modeling:** keep `chat_conversation.lastMessage` as a nullable many-to-one relation to `chat_message`. Do not duplicate latest message text/date onto `chat_conversation`. Load conversation lists with relation fields such as `lastMessage.id,lastMessage.text,lastMessage.createdAt`, update `lastMessage` after the message is persisted, and repair it in a `DELETE /chat_message` post-hook when deleting the current latest 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.',
@@ -270,6 +271,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **CRITICAL:** MUST call `create_record` or `update_record` on `extension_definition` — outputting Vue code in chat does NOT save it. User will NOT see it.',
     '- **Code format:** Vue SFC only. Structure: `<template>...</template>` + `<script setup>...</script>`. Server auto-compiles; if compile fails, fix and retry.',
     '- **NO import statements.** All APIs are injected globally (see full list below).',
+    '- **Design first for dashboards:** before creating/updating a dashboard extension, define the menu/page split, time range controls, tabs, and drill-down links. Keep `/dashboard` as overview; create focused menu pages for projects, provisioning, billing, infrastructure, and readiness when the surface grows.',
+    '- **Page layout default:** page extensions should render full-bleed inside the app shell by default. Do not wrap the entire page in a centered card/container unless explicitly requested. Use responsive grids/stacks from the first version so the page works on desktop, tablet, and mobile.',
+    '- **Do not downgrade extension code to ES5 to appease tooling.** eApp extension runtime should support normal browser/runtime APIs such as `Array.includes`, `Set`, `Promise.all`, `String.replace`, `Intl.DateTimeFormat`, and `Intl.NumberFormat`. If diagnostics reject these, fix eApp extension checker/runtime contract instead of rewriting generated extension code around the limitation.',
     '',
     '#### Injected Vue API functions:',
     '- Reactivity: `ref`, `reactive`, `computed`, `readonly`, `shallowRef`, `shallowReactive`',
@@ -311,6 +315,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **File Manager:** `FileManager`, `FileView`, `FileGridCard`, `CreateFolderModal`',
     '- **Menu:** `MenuRenderer`, `MenuItemEditor`',
     '- **UI:** `UButton`, `UCard`, `UInput`, `UTable`, `UBadge` (if available)',
+    '- **Tabs:** `UTabs` is available in current eApp extension runtime. Use it for page-level sections when a page would otherwise become too long.',
     '- **Extension:** `Widget` — embed widget extension via `<Widget :id="extensionId" />`',
     '- **WebSocket:** `WebSocketManager`',
     '- **Permission:** `PermissionGate`, `PermissionManager`',
@@ -323,6 +328,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **FormEditor field-map:** Customize fields via `:field-map`. Options: `label`, `description`, `hideLabel`, `hideDescription`, `component`, `componentProps`, `type`, `disabled`, `placeholder`, `permission`, `excludedOptions`/`includedOptions`, `fieldProps` (e.g. grid `class: \'md:col-span-2\'` when `layout=\'grid\'`), `booleanWrapperClass`, `fieldWrapperClass`. Optional `:sections` — array of `{ id, title?, hideHeading?, headingClass?, class?, rootClass?, fields: string[] }`; field order follows `fields`; unlisted columns render after. Custom input component: `modelValue` / `update:modelValue`.',
     '- **type "page":** Full-page extension. Requires `menu: { id }` — create menu first (`create_menu` or `create_record` on `menu_definition`), find by path/label, then create extension with `menu: { id: menuId }`. `menu_definition` uses **label** not name — filter by `label` or `path`.',
     '- **type "widget":** Widget extension. No menu required. Embed via `<Widget :id="extensionId" />` in other extensions or pages.',
+    '- **Existing pages:** if a menu already has a page extension, update that `extension_definition` record instead of creating a duplicate menu/extension. For example `/dashboard` is menu-driven and may already have an extension attached.',
     '',
     '#### NPM packages (install via MCP):',
     '- **Use `install_package` tool** — just pass the package name and type. The tool auto-fetches version from NPM, checks if already installed, and creates the record.',

package/src/lib/table-tools.js

@@ -112,7 +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.',
+      '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","isRead","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.',
@@ -130,7 +130,7 @@ 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"]]'),
+      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","isRead","conversation"],["conversation","member","isRead"]]'),
       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, indexes: indexesJson, uniques: uniquesJson }) => {
@@ -178,7 +178,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     [
       '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"]].',
+      '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","isRead","conversation"],["conversation","member","isRead"]].',
       'Run schema changes sequentially — migration locks DB per operation.',
     ].join(' '),
     {