@enfyra/mcp-server 0.0.67 → 0.0.68

package/package.json

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

package/src/lib/mcp-examples.js

@@ -1076,6 +1076,108 @@ create_extension({
           'eApp batch-fetches widget metadata requested in the same tick and caches loaded widgets, so render Widget components directly instead of manually fetching widget code.',
         ],
       },
+      {
+        name: 'Create a global shell extension for app-wide notifications',
+        code: `const notificationBellCode = \`
+<template></template>
+
+<script setup>
+const unread = ref(0)
+
+const NotificationBell = defineComponent({
+  name: 'NotificationBell',
+  setup() {
+    const openNotifications = () => navigateTo('/notifications')
+    return () => h(UButton, {
+      type: 'button',
+      icon: unread.value > 0 ? 'lucide:bell-ring' : 'lucide:bell',
+      color: unread.value > 0 ? 'primary' : 'neutral',
+      variant: unread.value > 0 ? 'solid' : 'ghost',
+      label: unread.value > 0 ? String(unread.value) : undefined,
+      onClick: openNotifications,
+    })
+  },
+})
+
+const { register } = useAccountPanelRegistry()
+register({
+  id: 'notifications',
+  order: 20,
+  component: NotificationBell,
+})
+
+const { adminSocket } = useAdminSocket()
+const handleNotification = (payload) => {
+  if (payload?.unread != null) unread.value = payload.unread
+}
+adminSocket.on('notification:summary', handleNotification)
+onUnmounted(() => {
+  adminSocket.off('notification:summary', handleNotification)
+})
+</script>
+\`
+
+create_extension({
+  type: "global",
+  name: "NotificationBellGlobal",
+  description: "Registers the app-wide notification bell in the account panel",
+  code: notificationBellCode,
+  isEnabled: true
+})`,
+        notes: [
+          'Global extensions are mounted invisibly by eApp 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.',
+          '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, keep the control compact: icon left, label/microcopy center, count/status badge right, one click target, and no floating card around it.',
+          'Destructure registry functions and register stable ids so reloads replace the same shell item predictably.',
+          'Remove socket or DOM listeners in onUnmounted; eApp unmounts old global components when extension cache reloads or the extension is disabled.',
+        ],
+      },
+      {
+        name: 'Design a global account-panel item with proper shell UI',
+        code: `<script setup>
+const unread = ref(3)
+
+const NotificationPanelItem = defineComponent({
+  name: 'NotificationPanelItem',
+  setup() {
+    const openNotifications = () => navigateTo('/notifications')
+    return () => h('button', {
+      type: 'button',
+      class: 'flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-left transition hover:bg-muted',
+      onClick: openNotifications,
+    }, [
+      h('span', {
+        class: 'flex h-9 w-9 shrink-0 items-center justify-center rounded-md bg-primary/10 text-primary',
+      }, [
+        h(UIcon, { name: unread.value > 0 ? 'lucide:bell-ring' : 'lucide:bell', class: 'h-5 w-5' }),
+      ]),
+      h('span', { class: 'min-w-0 flex-1' }, [
+        h('span', { class: 'block truncate text-sm font-medium text-highlighted' }, 'Notifications'),
+        h('span', { class: 'mt-0.5 block truncate text-xs text-muted' }, unread.value > 0 ? 'Needs review' : 'All caught up'),
+      ]),
+      unread.value > 0
+        ? h(UBadge, { color: 'primary', variant: 'soft', size: 'sm' }, () => String(unread.value))
+        : h(UIcon, { name: 'lucide:chevron-right', class: 'h-4 w-4 text-muted' }),
+    ])
+  },
+})
+
+const { register } = useAccountPanelRegistry()
+register({
+  id: 'notifications',
+  order: 20,
+  component: NotificationPanelItem,
+})
+</script>`,
+        notes: [
+          'Use this shape for shell/account-panel items: one row, aligned icon, readable label, short secondary text, and a compact trailing badge or chevron.',
+          'Do not use page-scale cards, hero headings, large whitespace, or a separate modal just to expose a shell entry.',
+          'Use `rounded-lg` or smaller radii, controlled padding, and the shell tokens/classes (`bg-muted`, `text-muted`, `text-highlighted`) so the item matches eApp.',
+          'Keep the entire row as one button with `type="button"`; avoid nested buttons inside account-panel rows.',
+          'Register the component from a `type="global"` extension, not from a page extension, when it must appear everywhere.',
+        ],
+      },
       {
         name: 'Page header and action button variants',
         code: `<script setup>
@@ -1143,8 +1245,9 @@ registerHeaderActions([
 //   await fetch menus
 //   rebuild menu registry with reset: true
 //   invalidate dynamic extension cache too, because route-to-extension mapping may change
-// if reload target is extension/menu or extension/global:
+// if reload target is extension or menu:
 //   clear dynamic extension component/meta cache
+//   reload enabled type="global" shell extensions
 
 // Verification pattern:
 // 1. Save the menu or extension record.

package/src/lib/mcp-instructions.js

@@ -311,7 +311,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Aggregate numeric rule:** `sum` and `avg` require a numeric field in ESV. Do not aggregate money stored as varchar/text. Use a numeric money field such as `amount_usd` with type `float`, `amount_cents`, or `amount` for revenue stats, or build a dedicated stats route that normalizes legacy values explicitly. If metadata says `float` but SQL aggregate still fails with `sum(character varying)`, the Enfyra Server physical schema is stale or missing the SQL float DDL mapping and must be redeployed/healed before relying on aggregate.',
     '- **Snapshot migrations:** backend metadata/physical schema renames belong in `data/snapshot-migration.json` via table-driven `columnsToModify` entries. The server migration/self-heal path should read table name plus `oldName`/`newName` dynamically; do not hard-code one-off table repairs when the snapshot migration contract can express the change.',
     '- **Partial reload default:** ESV/ASV automatically triggers partial reloads for metadata, routes, menus, extensions, flows, handlers, and related caches after successful writes. Do not reflexively call `/admin/reload`, `/admin/reload/metadata`, or `/admin/reload/routes` after each change. Verify naturally first; use manual reload only when verification shows stale behavior, a reload event failed, or a concrete error indicates the partial reload did not apply.',
-    '- **Menu/extension realtime reload contract:** `menu_definition` and `extension_definition` writes are runtime UI changes, not plain CRUD. The server cache orchestrator must emit `$system:reload` through the admin Socket.IO channel with identifiers that eApp handles; eApp must refetch menus/rebuild the menu registry for menu reloads and invalidate dynamic extension caches for extension reloads. Menu reloads can change route-to-extension mapping, so they should also invalidate extension cache. If an open admin tab does not reflect menu/extension changes, debug this two-sided reload contract before telling the user to refresh.',
+    '- **Menu/extension realtime reload contract:** `menu_definition` and `extension_definition` writes are runtime UI changes, not plain CRUD. The server cache orchestrator must emit `$system:reload` through the admin Socket.IO channel with identifiers that eApp handles; eApp must refetch menus/rebuild the menu registry for menu reloads, invalidate dynamic extension caches for extension reloads, and reload enabled `type="global"` shell extensions when extension/menu metadata changes. Menu reloads can change route-to-extension mapping, so they should also invalidate extension cache. If an open admin tab does not reflect menu/extension changes, debug this two-sided reload contract before telling the user to refresh.',
     '- **Dashboard stats:** time range buttons must change the query filter and reload stats. Dashboards should summarize actionable errors and high-level activity; successful/no-error background runs usually do not need a standalone page unless there is a real workflow to manage.',
     '- **Page layout default:** page extensions should render full-bleed inside the app shell by default. The extension root is already inside the eApp page `<main>`, so do not add root-level page padding such as `p-4 sm:p-6 xl:p-8`; use spacing between internal sections only. 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.',
     '- **PageHeader is mandatory for page extensions:** eApp already renders `CommonPageHeader` from `usePageHeaderRegistry()` in the app shell. Page extensions must call `const { registerPageHeader } = usePageHeaderRegistry()` and register app-level context such as `{ title, description, leadingIcon, gradient, variant }` instead of rendering their own top `<header>` inside extension content. Use `variant: "minimal"` for operational/admin detail pages unless the page intentionally needs a larger title strip.',
@@ -321,6 +321,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **HTTP method management:** use the dedicated MCP tools `list_methods`, `create_method`, `update_method`, and preview-first `delete_method` for `method_definition`. The backend field is `method_definition.name`, unique per method; do not send `method_definition.method`. The eApp UI for the same records is `/settings/methods`. Method color fields are `buttonColor` for badge background and `textColor` for badge text, both full hex colors. Do not use generic `create_record` on `method_definition` unless the dedicated tool is unavailable.',
     '- **Extension navigation:** prefer `NuxtLink` or Nuxt UI components with `:to` for visible navigation links and drill-down cards/buttons. Use `navigateTo(...)` only for imperative navigation after submit, confirm, mutation, or another side effect.',
     '- **Extension runtime scope:** eApp exposes Vue APIs and injected Nuxt/Enfyra composables both to script global scope and Vue app `globalProperties`. Template expressions may call injected helpers directly, for example after a save handler can call `navigateTo("/data/report_definition")`, because Vue compiles template helpers to `_ctx.*`.',
+    '- **Global extension lifecycle:** `extension_definition.type="global"` records are Vue SFC components mounted invisibly once at the eApp shell level. Use them for app-wide registrations such as account panel items, notification bells, admin socket listeners, and background refresh bridges. They do not need a menu, must not render page body UI, and should clean up socket/listener side effects with `onUnmounted`. Prefer registry composables such as `useAccountPanelRegistry`, `useHeaderActionRegistry`, or `useSubHeaderActionRegistry` instead of directly editing shell DOM.',
     '- **Extension realtime:** admin extensions can use `useAdminSocket()` to listen to the shared admin Socket.IO client instead of creating a separate browser socket. Use it for backend admin events such as operational status changes, debounce refreshes, and unsubscribe with `socket.off(...)` in `onUnmounted`. Guard generated code with `typeof useAdminSocket === "function"` when the extension may run on an older eApp build.',
     '- **Extension CSS affects shell utility ordering:** dynamic extension CSS is injected after the app shell CSS. Shell/page-header code must not put conflicting plain Tailwind utilities on the same element, such as `flex-col` plus `flex-row`, `items-start` plus `items-center`, or `text-left` plus `text-center`. Choose one mutually exclusive class per state; otherwise extension CSS can change which utility wins and shift shell layout.',
     '- **Admin record links:** when an admin extension links to backend records for management or inspection, point to eApp data routes such as `/data/report_definition` or `/data/order_definition`. Do not use public website paths from record fields unless the explicit intent is previewing the public website.',
@@ -358,6 +359,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **useConfirm:** Confirmation dialogs. Returns `{ confirm({ title, content, confirmText, cancelText }), isVisible, options, onConfirm, onCancel }`.',
     '- **useHeaderActionRegistry:** Register header actions. Use `const { register: registerHeaderActions } = useHeaderActionRegistry(); registerHeaderActions([{ id, label, onClick, color, icon, order, side, global, permission }])`. Action has `{ id, label, onClick, color, icon, order, side: \'left\'|\'right\', global, component, permission }`; admin actions should set `permission` by default.',
     '- **useSubHeaderActionRegistry:** Same as header but for sub-header: destructure `register` first, then call it with one action or an array.',
+    '- **useAccountPanelRegistry:** Register rows in the sidebar account panel. Use `const { register } = useAccountPanelRegistry(); register({ id, order, component, props })` or pass an array. The caller lifecycle unregisters rows automatically, so global extensions can register notification/account controls safely.',
     '- **usePageHeaderRegistry:** Page title strip. `{ registerPageHeader, clearPageHeader, pageHeader, hasPageHeader }`. Config: `title`, optional `description`, `stats`, `variant`, `gradient` (`purple`|`blue`|`cyan`|`none` — horizontal strip + leading icon tint), `leadingIcon` (icon name), `hideLeadingIcon`. Call `registerPageHeader` again when title/stats must update (plain object snapshot, not refs inside the config).',
     '- **useMenuRegistry:** Menu management. Returns `{ menuItems, menuGroups, registerMenuItem, unregisterMenuItem, getMenuItemsBySidebar, findParentMenuIdByPath }`.',
     '- **useMenuApi:** Low-level menu API.',
@@ -388,6 +390,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`. Sensitive/admin menus should pass a `permission` JSON object string to `create_menu` so visibility is permission-gated from creation.',
     '- **type "widget":** Widget extension. No menu required. Embed by numeric database id via `<Widget :id="123" />` in other extensions or pages.',
+    '- **type "global":** Global shell extension. No menu required and not embedded manually; eApp fetches all enabled global extensions during layout init and mounts them invisibly with normal Vue lifecycle. Use for global notification/account-panel/realtime registration code, not for route content. Keep `<template></template>` empty or minimal hidden markup, and keep visible UI in registered components or existing shell slots.',
     '- **Widget composition:** split large page extensions into widget extensions for bulky or reusable sections such as operation panels, status cards, timelines, tables, and sidebars. Keep tiny one-off markup in the page. Create/update the widget `extension_definition` rows first, then embed their ids from the page extension.',
     '- **Widget props/events:** the `Widget` wrapper forwards non-`id` attrs and listeners to the rendered widget component. Widget extensions can declare `defineProps` and `defineEmits`; parent prop changes are reactive like normal Vue component props. Use normal Vue syntax such as `<Widget :id="123" :project-id="projectId" :history-rows="historyRows" @refresh="refreshAll" />`; kebab-case attributes map to camelCase props.',
     '- **Widget state boundary:** do not mutate props inside widgets. Derive display state with `computed`, or mirror a prop into local mutable state with `watch(() => props.value, ...)` when the widget owns an editor draft. Prefer emitted events for child-to-parent actions; use callback function props only for parent-owned modal/drawer openers or imperative actions, and guard with `typeof action === "function"` inside the widget.',
@@ -432,7 +435,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `- \`update_record\` → PATCH \`${base}/<tableName>/<id>\` (optional tool queryParams append URL query)`,
     `- \`update_script_source\` → validates sourceCode with \`${base}/admin/script/validate\`, then PATCHes \`${base}/<script_table>/<id>\``,
     `- \`delete_record\` → DELETE \`${base}/<tableName>/<id>\` after preview + confirm=true (optional tool queryParams append URL query)`,
-    `- \`create_extension\` → POST \`${base}/extension_definition\` (Vue SFC only; for page pass menuId). \`update_record\` on extension_definition to change code.`,
+    `- \`create_extension\` → POST \`${base}/extension_definition\` (Vue SFC only; for \`type="page"\` pass menuId, for \`type="widget"\` or \`type="global"\` omit menuId). \`update_record\` on extension_definition to change code.`,
     `- Flow tables: \`${base}/flow_definition\`, \`${base}/flow_step_definition\`, \`${base}/flow_execution_definition\` — use standard CRUD tools.`,
     `- \`run_admin_test\` → POST \`${base}/admin/test/run\``,
     `- \`test_flow_step\` → POST \`${base}/admin/flow/test-step\``,

package/src/lib/table-tools.js

@@ -223,15 +223,18 @@ export function buildColumnDefinition({
   description,
   options,
 }) {
-  const column = { name, type };
-  if (isNullable !== undefined) column.isNullable = isNullable;
+  const column = {
+    name,
+    type,
+    isNullable: isNullable ?? true,
+    isPrimary: isPrimary ?? false,
+    isGenerated: isGenerated ?? false,
+    isSystem: isSystem ?? false,
+    isPublished: isPublished ?? true,
+    isUpdatable: isUpdatable ?? true,
+    isEncrypted: isEncrypted ?? false,
+  };
   if (isUnique !== undefined) column.isUnique = isUnique;
-  if (isPublished !== undefined) column.isPublished = isPublished;
-  if (isUpdatable !== undefined) column.isUpdatable = isUpdatable;
-  if (isEncrypted !== undefined) column.isEncrypted = isEncrypted;
-  if (isPrimary !== undefined) column.isPrimary = isPrimary;
-  if (isGenerated !== undefined) column.isGenerated = isGenerated;
-  if (isSystem !== undefined) column.isSystem = isSystem;
   if (defaultValue !== undefined) column.defaultValue = defaultValue;
   if (description !== undefined) column.description = description;
   if (options !== undefined) column.options = JSON.parse(options);

package/src/mcp-server-entry.mjs

@@ -2404,20 +2404,26 @@ server.tool('create_menu', 'Create a menu item in the navigation. Use permission
 server.tool(
   'create_extension',
   [
-    'Create an extension (Vue SFC page or widget). Code must be Vue SFC: <template>...</template> + <script setup>...</script> — NO imports, use globals (ref, useToast, useApi, UButton, etc).',
-    'For type=page: create menu first (create_menu), get id, then pass menuId. For type=widget no menu needed. Server auto-compiles and should emit realtime reload to open eApp tabs. See extension rules in MCP instructions.',
+    'Create an extension (Vue SFC page, widget, or global shell extension). Code must be Vue SFC: <template>...</template> + <script setup>...</script> — NO imports, use globals (ref, useToast, useApi, UButton, etc).',
+    'For type=page: create menu first (create_menu), get id, then pass menuId. For type=widget: no menu, embed via <Widget>. For type=global: no menu, eApp mounts it invisibly at shell level for registries/realtime. Server auto-compiles and should emit realtime reload to open eApp tabs. See extension rules in MCP instructions.',
   ].join(' '),
   {
     name: z.string().describe('Extension name (unique)'),
-    type: z.enum(['page', 'widget']).describe('Extension type: page = full page linked to menu; widget = embed via Widget component'),
+    type: z.enum(['page', 'widget', 'global']).describe('Extension type: page = full page linked to menu; widget = embed via Widget component; global = shell-level lifecycle component'),
     code: z.string().describe('Vue SFC string — <template> + <script setup>, NO import statements'),
-    menuId: z.string().optional().describe('Required for type=page — menu_definition id from create_menu. Omit for widget'),
+    menuId: z.string().optional().describe('Required for type=page — menu_definition id from create_menu. Omit for widget/global'),
     isEnabled: z.boolean().optional().default(true).describe('Enable extension'),
     description: z.string().optional().describe('Extension description'),
     version: z.string().optional().default('1.0.0').describe('Extension version'),
   },
   async (data) => {
     const body = { ...data };
+    if (body.type === 'page' && !body.menuId) {
+      throw new Error('menuId is required for type=page. Create or find a menu_definition record first.');
+    }
+    if (body.type !== 'page' && body.menuId) {
+      throw new Error('menuId is only valid for type=page. Omit menuId for widget/global extensions.');
+    }
     if (body.menuId) {
       body.menu = { id: body.menuId };
       delete body.menuId;