@enfyra/mcp-server 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -1,7 +1,15 @@
+export const EXAMPLE_REASONING_GUIDE = [
+  'Examples are reasoning anchors, not templates to copy blindly. Preserve the platform contract, then adapt table names, route paths, relation names, fields, UI labels, and lifecycle triggers to the live app.',
+  'First identify the invariant being demonstrated: security boundary, query shape, shell registry contract, schema relation direction, runtime lifecycle, or browser proxy pattern.',
+  'Then identify what is illustrative: chat/order/report/cloud paths, sample field names, icons, labels, menu order, and specific notification kinds.',
+  'When a note says do not, treat it as a contract or safety boundary unless live metadata proves a different supported contract. When a note says for example, map the idea to the current domain instead of copying the literal names.',
+  'Before applying an example, inspect live metadata/routes/features and choose the closest supported tool. Use the smallest example that proves the decision, then compose with other examples only when the task truly needs multiple contracts.',
+];
+
 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.',
+    useWhen: 'Use when building Nuxt, Next, or another browser app that should rely on Enfyra cookies through an app-origin proxy; adapt the framework-specific wrapper while preserving the same-origin proxy and cookie boundary.',
     examples: [
       {
         name: 'Nuxt routeRules for REST and Socket.IO',
@@ -550,6 +558,7 @@ update_record({
   ])
 })`,
         notes: [
+          'Chat is the illustrative domain here. For another domain, keep the same modeling question: what is the parent entity, what is stored on the parent, and what belongs on child rows?',
           '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.',
@@ -584,6 +593,7 @@ update_record({
   ])
 })`,
         notes: [
+          'The relation names conversation and sender are examples of domain language; choose relation property names that match the entity model users reason about.',
           'Use enfyra_user as the user table.',
           'Use table ids for targetTable when already known; MCP can also resolve exact table names such as "enfyra_user" before schema mutation.',
           'Do not add inverse relations on enfyra_user unless a concrete user-to-record response, UI, or deep query will use it.',
@@ -606,6 +616,7 @@ update_record({
         notes: [
           'Use inversePropertyName only when the parent table will actually expose, deep-load, count, or sort by that child collection.',
           'For example, conversation.messages is justified if a conversation detail response loads the latest message page with deep.messages limit/sort, or if a list sorts by _max(messages.createdAt).',
+          'Translate this to the current domain by asking whether the parent screen needs a child collection or aggregate; if not, keep the relation one-directional.',
           'If the app only filters chat_message by conversation.id, omit inversePropertyName and keep the schema one-directional.',
           'Before creating an inverse, inspect existing relations and state why the reverse traversal is needed.',
         ],
@@ -754,6 +765,7 @@ create_column({
           'Use a conversation read pre-hook/RLS boundary so the route only returns conversations visible to @USER.',
           'lastMessage is a relation to chat_message; do not duplicate preview fields on chat_conversation.',
           'all: true tells MCP to send REST limit=0 and load all matching conversation rows.',
+          'This is a small bounded user inbox example. For larger inventories, prefer pagination even when RLS scopes the records.',
           'Do not fetch messages for every conversation on initial list load; load messages after selecting a conversation.',
         ],
       },
@@ -807,6 +819,7 @@ GET /enfyra/post?filter={"<primaryKeyFromMetadata>":{"_eq":123}}&limit=1`,
         notes: [
           'Use fields with dotted relation paths when you only need scalar fields from related records.',
           'This is enough for simple many-to-one or one-to-one relation display such as owner.email, customer.name, or lastMessage.text.',
+          'Treat order/customer as placeholders; the transferable idea is "show parent rows with a few scalar relation fields".',
           'Do not add deep when fields alone can express the relation data you need.',
         ],
       },
@@ -894,6 +907,7 @@ query_table({
         notes: [
           'Use _max(relation.field) for latest-child ordering, _min(relation.field) for earliest-child ordering, and _count(relation) for child-count ordering.',
           'Aggregate sort helpers only work on direct one-to-many or many-to-many list relations.',
+          'Support tickets and messages are illustrative. Apply this when a parent list must be ordered by child recency or child volume.',
           'The aggregate field must be a real published, non-encrypted scalar field on the related table for user-facing APIs.',
           'Do not use _max, _min, or _count on private relations or unpublished fields unless the endpoint intentionally exposes that fact.',
           'Do not use raw sort=-messages.createdAt for parent ordering; it is ambiguous and rejected.',
@@ -1510,7 +1524,7 @@ return saved`,
   },
   extensions: {
     title: 'Dynamic app extensions and menus',
-    useWhen: 'Use when adding custom UI pages to the Enfyra app.',
+    useWhen: 'Use when adding custom Enfyra admin UI pages, widgets, global shell integrations, menu entries, account-panel rows, or shell attention signals.',
     examples: [
       {
         name: 'Create or update HTTP method colors',
@@ -1562,6 +1576,7 @@ ensure_page_extension({
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
+          'Reports is an illustrative page. Keep the shell/page contracts, but choose the real route, menu label, icon, permissions, and body layout from the operator workflow.',
           'Menu provides navigation; extension provides content.',
           'Use enfyra_menu.label, not title.',
           'Sensitive admin menus should include a permission condition at creation time.',
@@ -1645,6 +1660,7 @@ ensure_page_extension({
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
+          'This shows composition mechanics. Replace reports/status/table with domain sections that are independently reusable or complex enough to deserve widgets.',
           'Use widgets for bulky or reusable sections such as operation panels, timelines, tables, sidebars, and status cards.',
           'Embed widgets by their numeric enfyra_extension id, not by extensionId/name.',
           'Props and listeners pass through the Widget wrapper. Widget defineProps values update reactively when the parent refs/computed values change.',
@@ -1705,13 +1721,17 @@ register({
 
 const { register: registerMenuNotification, unregister: unregisterMenuNotification } = useMenuNotificationRegistry()
 watchEffect(() => {
-  registerMenuNotification({
-    id: 'notifications-menu-unread',
-    target: { path: '/notifications' },
-    value: notificationBadge.value,
-    color: unread.value > 0 ? 'error' : 'neutral',
-    title: notificationDescription.value,
-  })
+  if (notificationBadge.value) {
+    registerMenuNotification({
+      id: 'notifications-menu-unread',
+      target: { path: '/notifications' },
+      value: notificationBadge.value,
+      color: 'error',
+      title: notificationDescription.value,
+    })
+  } else {
+    unregisterMenuNotification('notifications-menu-unread')
+  }
 })
 
 const { adminSocket } = useAdminSocket()
@@ -1736,7 +1756,10 @@ ensure_global_extension({
         notes: [
           'Global extensions are mounted invisibly by Enfyra admin UI during layout init; do not create a menu and do not embed them with Widget.',
           'Use them for shell-level registrations, realtime listeners, notification counters, account panel rows, and background refresh bridges.',
+          'The notification center is only one possible shell integration. The transferable shape is invisible global extension -> shell registry -> cleanup on unmount.',
           'Use useMenuNotificationRegistry for sidebar menu counts/dots when notification state should be visible in the menu as well as the notification center.',
+          'Choose value only when the signal source already owns an exact count. Omit value for a dot when realtime only proves that something new exists.',
+          'Do not fetch the destination domain list just to decorate a menu. A mail page fetches mail; a support page fetches tickets; the shell should use notification or summary signals.',
           'Keep the global extension template empty or hidden; visible UI should be registered into an existing shell registry or component slot.',
           'For account-panel UI, register data-driven row fields so Enfyra admin UI owns icon size, row spacing, badge placement, hover state, and expanded chrome.',
           'Use contentComponent only for expanded inner content; use raw component only as an escape hatch when the row cannot fit the shell contract.',
@@ -1744,6 +1767,160 @@ ensure_global_extension({
           'Remove socket or DOM listeners in onUnmounted; The Enfyra admin UI unmounts old global components when extension cache reloads or the extension is disabled.',
         ],
       },
+      {
+        name: 'Signal menu attention without polling destination lists',
+        code: `const signalBridgeCode = \`
+<template></template>
+
+<script setup>
+const attentionRows = ref([])
+const notificationSignal = ref(false)
+const route = useRoute()
+
+const notificationApi = useApi('/cloud_admin_notifications', {
+  query: {
+    filter: JSON.stringify({ readAt: { _is_null: true } }),
+    fields: 'id,kind,targetPath,readAt',
+    sort: '-createdAt,-id',
+    limit: 10,
+  },
+})
+
+const hasNewEmail = computed(() =>
+  attentionRows.value.some((row) => row.kind === 'email_inbound' && !row.readAt)
+)
+const hasNewSupport = computed(() =>
+  attentionRows.value.some((row) => row.kind === 'support' && !row.readAt)
+)
+const accountBadge = computed(() => notificationSignal.value ? 'New' : null)
+const accountDescription = computed(() => notificationSignal.value ? 'New admin attention' : 'All caught up')
+
+function syncFromNotificationRows() {
+  const value = notificationApi.data?.value
+  const rows = Array.isArray(value?.data)
+    ? value.data
+    : Array.isArray(value?.data?.data)
+      ? value.data.data
+      : []
+  attentionRows.value = rows
+  notificationSignal.value = rows.some((row) => !row.readAt)
+}
+
+async function refreshNotificationSignals() {
+  await notificationApi.execute()
+  syncFromNotificationRows()
+}
+
+const { register: registerAccountPanel } = useAccountPanelRegistry()
+registerAccountPanel({
+  id: 'admin-attention',
+  order: 20,
+  label: 'Notifications',
+  icon: computed(() => notificationSignal.value ? 'lucide:bell-ring' : 'lucide:bell'),
+  description: accountDescription,
+  count: accountBadge,
+  badgeColor: 'info',
+  onClick: () => navigateTo('/data/cloud_admin_notifications'),
+})
+
+const { register: registerMenuNotification, unregister: unregisterMenuNotification } = useMenuNotificationRegistry()
+watchEffect(() => {
+  if (hasNewEmail.value) {
+    registerMenuNotification({
+      id: 'attention-email',
+      target: { path: '/email/messages' },
+      color: 'info',
+      title: 'New inbound email',
+    })
+  } else {
+    unregisterMenuNotification('attention-email')
+  }
+
+  if (hasNewSupport.value) {
+    registerMenuNotification({
+      id: 'attention-support',
+      target: { path: '/cloud/support' },
+      color: 'info',
+      title: 'New support activity',
+    })
+  } else {
+    unregisterMenuNotification('attention-support')
+  }
+})
+
+watch(() => route.path, (path) => {
+  if (path.startsWith('/email/messages')) {
+    attentionRows.value = attentionRows.value.filter((row) => row.kind !== 'email_inbound')
+  }
+  if (path.startsWith('/cloud/support')) {
+    attentionRows.value = attentionRows.value.filter((row) => row.kind !== 'support')
+  }
+  notificationSignal.value = attentionRows.value.some((row) => !row.readAt)
+})
+
+const { adminSocket } = useAdminSocket()
+function handleAdminNotification(payload) {
+  refreshNotificationSignals()
+  if (payload?.kind === 'email_inbound') {
+    registerMenuNotification({ id: 'attention-email', target: { path: '/email/messages' }, color: 'info', title: 'New inbound email' })
+  }
+  if (payload?.kind === 'support') {
+    registerMenuNotification({ id: 'attention-support', target: { path: '/cloud/support' }, color: 'info', title: 'New support activity' })
+  }
+}
+
+function getAdminSocket() {
+  return adminSocket && adminSocket.value !== undefined ? adminSocket.value : adminSocket
+}
+
+function bindAdminSocket(socket) {
+  if (socket && typeof socket.on === 'function') {
+    socket.on('admin:notification-created', handleAdminNotification)
+  }
+}
+
+function unbindAdminSocket(socket) {
+  if (socket && typeof socket.off === 'function') {
+    socket.off('admin:notification-created', handleAdminNotification)
+  }
+}
+
+if (adminSocket && adminSocket.value !== undefined) {
+  watch(adminSocket, (nextSocket, previousSocket) => {
+    unbindAdminSocket(previousSocket)
+    bindAdminSocket(nextSocket)
+  })
+}
+
+onMounted(() => {
+  refreshNotificationSignals()
+  bindAdminSocket(getAdminSocket())
+})
+onUnmounted(() => {
+  unbindAdminSocket(getAdminSocket())
+  unregisterMenuNotification('attention-email')
+  unregisterMenuNotification('attention-support')
+})
+</script>
+\`
+
+ensure_global_extension({
+  name: "AdminAttentionSignalBridge",
+  description: "Routes notification signals into account-panel and sidebar menu attention markers without polling destination lists",
+  code: signalBridgeCode,
+  isEnabled: true,
+  extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
+})`,
+        notes: [
+          'Use this reasoning pattern when the shell should show attention but the destination page owns the expensive or domain-specific list fetch.',
+          'This example fetches only the notification source of truth, not the email, support, order, or job tables. Substitute your own notification or summary endpoint when available.',
+          'Omitting value on registerMenuNotification renders a dot. That is the right promise when the shell knows "new work exists" but not an exact count.',
+          'If a backend summary event already includes an exact unread count, use value for a count chip. If the event only says one record changed, use a dot and let the page fetch details.',
+          'Map notification kinds to menu targets by product meaning, not by copying these paths. For example, approval_required could target /reviews, failed_job could target /operations/jobs, and quota_warning could target /billing.',
+          'Generalize the lifecycle: seed from a bounded signal source, react to realtime events, clear local attention when the user reaches the owning page, and avoid duplicating that page\'s data fetch.',
+          'Clear local dot signals when the user enters the destination route or when the notification center marks the underlying notification as read.',
+        ],
+      },
       {
         name: 'Register a data-driven account-panel item',
         code: `<script setup>
@@ -1780,6 +1957,7 @@ register({
 </script>`,
         notes: [
           'Prefer this contract for shell/account-panel items: data fields for the row, optional contentComponent for the expanded body.',
+          'Notifications is illustrative. Account-panel rows can represent any account-scoped attention or shortcut, such as approvals, billing, deployments, or personal tasks.',
           'Use count for the primary visible badge value. badge remains supported as a legacy alias, but count is what the account trigger aggregates.',
           'Do not draw a custom full row with page-scale cards, hero headings, large whitespace, or nested buttons unless the shell contract cannot express the UI.',
           'Let the Enfyra admin UI handle the row button, icon container, label, microcopy, badge, chevron, hover state, spacing, and expanded wrapper.',
@@ -1834,6 +2012,7 @@ registerHeaderActions([
 </script>`,
         notes: [
           'Use PageHeader for the title strip; do not render a duplicate header inside extension body.',
+          'The exact actions are illustrative. Choose action prominence from user intent: navigation, secondary utility, primary mutation, or destructive confirmation.',
           'Use gradient: "none" for generated operational pages; hardcoded named gradients are decorative and should be explicit user intent.',
           'Back/navigation actions should be neutral ghost so they read as navigation, not a primary operation.',
           'Visible secondary operations should be neutral outline; soft is only for low-emphasis chrome actions.',
@@ -1873,7 +2052,7 @@ registerHeaderActions([
       },
       {
         name: 'Plan an admin dashboard as multiple pages',
-        code: `// Recommended menu shape for an operations surface:
+        code: `// Illustrative menu shape for an operations surface:
 ensure_menu({
   type: "Dropdown Menu",
   label: "Operations",
@@ -1899,6 +2078,7 @@ ensure_menu({
 // For admin record management, link to /data/<table>, e.g. /data/report, not public website paths.`,
         notes: [
           'Design the menu/page split before generating dashboard code.',
+          'Operations/jobs/orders/reports/settings are examples of separating mental models. Replace them with the real domains users navigate between.',
           'Permission-gate sensitive parent dropdown menus too, using any child page route or backing route that represents read access.',
           'Keep /dashboard as a summary and distribution page, not a detailed operations table.',
           'Use focused pages for operational domains.',
@@ -1930,6 +2110,7 @@ onMounted(() => fetchOrders())
         notes: [
           'Use app-provided composables in extensions.',
           'useApi does not auto-run; call execute() on mounted or through an action.',
+          'The /order path is illustrative; inspect routes and fetch the smallest data shape the extension needs.',
           'Keep extension UI focused; move backend logic into handlers/hooks when needed.',
         ],
       },
@@ -2056,6 +2237,7 @@ onMounted(() => Promise.all([flowStats.execute(), orderStats.execute()]))
           'Aggregate keys must be real fields or relations.',
           'Read results from response.meta.aggregate.',
           'Use top-level filter for time windows and cross-field conditions.',
+          'The flow/order pair is illustrative. Choose aggregates that answer the page question, such as failed work, pending approvals, unread support, quota pressure, or revenue.',
           'Only aggregate fields and relations that the dashboard is allowed to expose; aggregate values can reveal hidden data even when rows omit that field.',
           'sum/avg require numeric fields; amount_usd must be a real float/numeric SQL column, not metadata-only float over a varchar physical column.',
         ],
@@ -2075,6 +2257,7 @@ export function listExampleCategories() {
 export function getExamples(category) {
   if (!category) {
     return {
+      reasoningGuide: EXAMPLE_REASONING_GUIDE,
       categories: listExampleCategories(),
       hint: 'Call get_enfyra_examples with one category key to retrieve concrete examples for that area.',
     };
@@ -2090,6 +2273,7 @@ export function getExamples(category) {
 
   return {
     category,
+    reasoningGuide: EXAMPLE_REASONING_GUIDE,
     ...entry,
   };
 }

package/src/lib/platform-operation-tools.js

@@ -305,6 +305,7 @@ function getExtensionThemeContract() {
       'Page extensions should be full-bleed, responsive, and split large operations into focused pages or UTabs.',
       'Use usePageHeaderRegistry for the shell title and useHeaderActionRegistry/useSubHeaderActionRegistry for page actions.',
       'Use useMenuNotificationRegistry from global extensions to register sidebar menu notification counts or dots. Register stable ids, target menus by id/path/route, use value for counts, omit value for a dot, and choose color from primary/success/warning/error/info/neutral.',
+      'For shell menu notifications, first decide the signal source. Use a count only when the source already owns an exact count, such as a notification summary endpoint or bounded unread-notification query. Use a dot when a realtime event only proves that something new exists. Do not poll a domain list such as messages, tickets, orders, or jobs solely to decorate the menu; the destination page owns domain fetching.',
       'Use useAccountPanelRegistry for account panel rows. AccountPanelItem supports count as the preferred numeric/text badge value, badge as a legacy alias, and badgeColor primary/neutral/info/error/warning/success.',
       'For detail/form workflows that should stay left-aligned with empty space on the right, wrap the body in eapp-page-constrained; use eapp-page-constrained-wide only when the workflow genuinely needs more width.',
       'Card/list grids inside the default shell must account for the 280px desktop sidebar. Do not switch general card grids to three columns at lg; use md:grid-cols-2 xl:grid-cols-3 unless a local container proves three columns have enough width.',
@@ -416,6 +417,7 @@ function getExtensionThemeContract() {
       menu: 'useMenuNotificationRegistry().register({ id, target: { id?, path?, route? }, value?, color?, title?, order? }). value renders a count/chip; omitting value renders a dot. Parent menus sum numeric child values.',
       accountPanel: 'useAccountPanelRegistry().register({ id, label, description, icon, count?, badge?, badgeColor?, expanded?, onToggle?, contentComponent? }). count is preferred over badge and the account trigger sums numeric visible item counts, capped at 99+.',
       lifecycle: 'Register from global extensions for app-wide notification state; stable ids replace previous registrations and component-owned registrations are removed on unmount.',
+      reasoning: 'Counts and dots are different promises. A count says the shell knows an exact or bounded number from an appropriate notification/summary source. A dot says the shell only knows that new attention exists. Avoid fetching the destination domain list just to make a menu badge more precise.',
     },
     contractAuthority: [
       'This is the authoritative Enfyra theme & color contract. Source of truth: documents/app/theme-color-contract.md. The app owns color through app/utils/primary-colors.ts (Material You seed-to-role generation), app/assets/css/theme.css (semantic variables and Nuxt UI ramps), app/assets/css/main.css (extension-safe semantic utilities), and app/app.config.ts (Nuxt UI component mapping). Pages and extensions only CONSUME classes/Nuxt UI props; they never define colors.',