@enfyra/mcp-server 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.1.3",
+  "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

@@ -1705,13 +1705,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()
@@ -1737,6 +1741,8 @@ ensure_global_extension({
           '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.',
@@ -1744,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>

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.',