@enfyra/mcp-server 0.1.2 → 0.1.4

package/package.json

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

package/src/lib/mcp-examples.js

@@ -1694,7 +1694,7 @@ register({
   label: 'Notifications',
   icon: notificationIcon,
   description: notificationDescription,
-  badge: notificationBadge,
+  count: notificationBadge,
   badgeColor: 'error',
   expanded,
   onToggle: () => {
@@ -1703,6 +1703,21 @@ register({
   contentComponent: NotificationList,
 })
 
+const { register: registerMenuNotification, unregister: unregisterMenuNotification } = useMenuNotificationRegistry()
+watchEffect(() => {
+  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()
 const handleNotification = (payload) => {
   if (payload?.unread != null) unread.value = payload.unread
@@ -1710,6 +1725,7 @@ const handleNotification = (payload) => {
 adminSocket.on('notification:summary', handleNotification)
 onUnmounted(() => {
   adminSocket.off('notification:summary', handleNotification)
+  unregisterMenuNotification('notifications-menu-unread')
 })
 </script>
 \`
@@ -1724,6 +1740,9 @@ 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.',
+          '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.',
@@ -1731,6 +1750,159 @@ 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 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.',
+          '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>
@@ -1739,7 +1911,7 @@ const expanded = ref(false)
 
 const label = 'Notifications'
 const icon = computed(() => unread.value > 0 ? 'lucide:bell-ring' : 'lucide:bell')
-const badge = computed(() => unread.value > 0 ? String(unread.value) : null)
+const count = computed(() => unread.value > 0 ? String(unread.value) : null)
 const description = computed(() => unread.value > 0 ? 'Needs review' : 'All caught up')
 
 const NotificationPanelContent = defineComponent({
@@ -1756,7 +1928,7 @@ register({
   label,
   icon,
   description,
-  badge,
+  count,
   badgeColor: 'error',
   expanded,
   onToggle: () => {
@@ -1767,6 +1939,7 @@ register({
 </script>`,
         notes: [
           'Prefer this contract for shell/account-panel items: data fields for the row, optional contentComponent for the expanded body.',
+          '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.',
           'Keep contentComponent compact; it is rendered inside account-panel chrome and should not create another large card around itself.',

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

@@ -304,6 +304,9 @@ function getExtensionThemeContract() {
       'The extension is already mounted inside the Enfyra app shell. Do not add a duplicate page header, centered page wrapper, or root-level page padding.',
       '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.',
     ],
@@ -359,6 +362,7 @@ function getExtensionThemeContract() {
       'Use CommonDrawer for side-panel editing. Open drawers immediately on user action and render loading/error/content inside the drawer instead of waiting for fetch before opening.',
       'Use UTabs for page sections and large grouped forms instead of custom tab bars; the app-level Nuxt UI override owns active and inactive indicators, focus rings, spacing, and theme contrast.',
       'Use UBadge or token-backed badge spans for status. Keep badges legible in both themes with tokenized background, text, and border.',
+      'Use shell registries for shell badges: useAccountPanelRegistry for the account panel and useMenuNotificationRegistry for sidebar menus. Do not draw detached fixed-position badges over the app shell.',
     ],
     loadingAndLists: [
       'For first load of card/list pages, render calm skeleton cards with a slow pulse. Use USkeleton or shared loading components so the app-owned skeleton theme controls contrast and accent matching. For subsequent pagination/filter refreshes, keep the card shells mounted and skeletonize card content until the new list is ready.',
@@ -409,6 +413,12 @@ function getExtensionThemeContract() {
       },
     ],
     compactExample: '<template><section class="min-h-full w-full space-y-4"><article class="eapp-surface-card p-4"><div class="flex items-start justify-between gap-3"><div><p class="text-sm eapp-text-tertiary">Neutral KPI</p><p class="mt-2 text-2xl font-semibold eapp-text-primary">24</p></div><span class="eapp-primary-soft eapp-icon-tile"><UIcon name="lucide:square-stack" class="size-5 eapp-primary-text" /></span></div><div class="mt-3 h-1.5 overflow-hidden eapp-radius-pill eapp-surface-muted"><div class="eapp-primary-solid h-full w-1/2"></div></div></article><section class="eapp-surface-card p-4"><div class="flex items-center justify-between gap-3"><p class="font-semibold eapp-text-primary">Status block stays neutral</p><UBadge color="success" variant="soft">Healthy</UBadge></div></section></section></template>',
+    shellNotificationContract: {
+      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.',
       'Every color flows from two base layers: --md-* (Material You, runtime primary picker) and --st-* (status). Runtime primary roles are generated with SchemeTonalSpot. Success/warning/info stay fixed status quarts; error follows the generated Material error role through the single --danger-* lane. All Nuxt UI semantic colors (primary/secondary/success/warning/error/info/neutral) are re-pointed to these, so Nuxt UI is used per its docs but colors are decided by Enfyra. This applies to the shell, system pages, and compiled dynamic extensions.',

package/src/lib/required-knowledge.js

@@ -109,6 +109,7 @@ export function buildRequiredKnowledgePayload() {
           'Prefer FormEditor/FormEditorLazy for direct table-backed forms when the form maps to metadata fields.',
           'For long admin setup workflows, open CommonDrawer immediately and show loading/error/content inside it.',
           'Use Widget with numeric enfyra_extension widget ids; pass safe reactive props/events and keep page-level mutation ownership in the page unless the widget intentionally owns the workflow.',
+          'Use useMenuNotificationRegistry for sidebar menu counts/dots and useAccountPanelRegistry count/badge fields for account panel notifications; register these from global extensions when they should update across the shell.',
         ],
       },
     ],