@enfyra/mcp-server 0.1.5 → 0.1.7

package/README.md

@@ -244,14 +244,14 @@ Use `get_enfyra_examples` from the MCP tool list when asking an LLM to generate
 - files and storage
 - Enfyra admin extensions
 
-Use `get_enfyra_required_knowledge` before asking an LLM to save dynamic server code or Enfyra extension code. It returns short required contracts plus acknowledgement keys that code-writing tools verify before saving.
+Use `get_enfyra_required_knowledge` before asking an LLM to mutate metadata, schema, routes, permissions, menus, packages, cache state, dynamic server code, or Enfyra extension code. It returns global rules plus acknowledgement keys that write tools verify before saving. Dynamic server code also requires the dynamic-code acknowledgement key, and extension code also requires the extension acknowledgement key.
 
 ## Runtime Safety
 
 The MCP server includes safety guards for LLM callers:
 
 - Generic record mutations validate fields against live metadata.
-- Code-writing tools require `get_enfyra_required_knowledge` acknowledgement before saving dynamic scripts or extension code. Discovery, validation, and preview tools remain available without the acknowledgement so agents can read and plan first.
+- Write tools require `get_enfyra_required_knowledge` acknowledgement before mutating Enfyra state. Discovery, validation, and preview tools remain available without the acknowledgement so agents can read and plan first. If the acknowledgement is missing, the tool error tells the caller to read `get_enfyra_required_knowledge` and pass the required key.
 - Script-backed records validate `sourceCode` through `/admin/script/validate` before saving.
 - `validate_dynamic_script` checks handler, hook, flow, websocket, GraphQL, and bootstrap script source without saving.
 - `validate_extension_code` checks Enfyra admin extension code through `/enfyra_extension/preview` without saving.

package/package.json

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

package/src/lib/mcp-examples.js

@@ -551,6 +551,7 @@ update_record({
         name: 'Create a chat conversation table',
         code: `create_table({
   name: "chat_conversation",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   columns: JSON.stringify([
     { name: "kind", type: "varchar", isNullable: false, defaultValue: "dm" },
     { name: "title", type: "varchar", isNullable: true },
@@ -568,6 +569,7 @@ update_record({
         name: 'Create relations directly to enfyra_user',
         code: `create_table({
   name: "chat_message",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   columns: JSON.stringify([
     { name: "text", type: "text", isNullable: false },
     { name: "persistStatus", type: "varchar", defaultValue: "persisted" }
@@ -607,6 +609,7 @@ update_record({
         code: `create_relation({
   sourceTableId: "chat_message",
   targetTableId: "chat_conversation",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   propertyName: "conversation",
   inversePropertyName: "messages",
   type: "many-to-one",
@@ -625,6 +628,7 @@ update_record({
         name: 'Add chat_conversation.lastMessage after chat_message exists',
         code: `update_table({
   tableId: "<chat_conversation_id>",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   relations: JSON.stringify([
     {
       propertyName: "createdBy",
@@ -651,6 +655,7 @@ update_record({
         name: 'Unread/read table with unique and indexes',
         code: `create_table({
   name: "chat_message_read",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   columns: JSON.stringify([
     { name: "isRead", type: "boolean", defaultValue: false },
     { name: "readAt", type: "datetime", isNullable: true }
@@ -677,6 +682,7 @@ update_record({
         code: `create_column({
   tableId: "<enfyra_user_table_id>",
   name: "emailVerifiedAt",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   type: "datetime",
   isNullable: true,
   isPublished: true,
@@ -686,6 +692,7 @@ update_record({
 create_column({
   tableId: "<enfyra_user_table_id>",
   name: "emailVerificationStatus",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   type: "varchar",
   isNullable: false,
   defaultValue: "pending",
@@ -696,6 +703,7 @@ create_column({
 create_column({
   tableId: "<integration_secret_table_id>",
   name: "value",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   type: "text",
   isNullable: false,
   isPublished: false,
@@ -722,6 +730,7 @@ create_column({
 create_column({
   tableId: "<table_id>",
   name: "api_secret",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   type: "text",
   isPublished: false,
   isEncrypted: true
@@ -923,6 +932,7 @@ GET /enfyra/integrations?filter={"api_token":{"_eq":"plaintext-token"}}
 create_column({
   tableId: "<integrations_table_id>",
   name: "api_token_lookup_sha256",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   type: "varchar",
   isNullable: false,
   isPublished: false
@@ -958,6 +968,7 @@ const found = await #integrations.find({
   routeId: "<route_id>",
   method: "POST",
   scriptLanguage: "javascript",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
   sourceCode: \`const email = @BODY.email
 if (!email) @THROW400("Email is required")
@@ -966,7 +977,7 @@ return { ok: true, email }\`
 })`,
         notes: [
           'Use sourceCode, not logic. The server generates compiledCode.',
-          'Call get_enfyra_required_knowledge before saving dynamic code and pass dynamicCodeAckKey as knowledgeAckKey.',
+          'Call get_enfyra_required_knowledge before saving dynamic code, pass globalRulesAckKey as globalRulesAckKey, and pass dynamicCodeAckKey as knowledgeAckKey.',
           'Use method for one handler, or methods only when the same sourceCode should be saved for multiple methods.',
           'Do not pass name to enfyra_route_handler; one handler is identified by route + method.',
         ],
@@ -1020,6 +1031,7 @@ const scope = {
         name: 'Encrypted field table definition',
         code: `create_table({
   name: "integrations",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   columns: JSON.stringify([
     { name: "name", type: "varchar", isNullable: false },
     {
@@ -1047,6 +1059,7 @@ const scope = {
   name: "strip_email_verification_fields",
   methods: ["PATCH"],
   priority: -10,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
   code: \`delete @BODY.emailVerifiedAt
 delete @BODY.emailVerificationStatus
@@ -1065,6 +1078,7 @@ delete @BODY.emailVerificationSentAt\`
   name: "shape_display_title",
   methods: ["GET"],
   priority: 0,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
   code: \`if (@ERROR) {
   @LOGS("Request failed", @ERROR.message)
@@ -1558,6 +1572,7 @@ update_method({
   icon: "lucide:bar-chart-3",
   order: 20,
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   permission: JSON.stringify({
     or: [
       { route: "/reports", methods: ["GET"] },
@@ -1573,6 +1588,7 @@ ensure_page_extension({
   menuId: "<created-menu-id>",
   code: "<template><section class=\\"min-h-full w-full space-y-4\\"><div class=\\"grid gap-4 md:grid-cols-2 xl:grid-cols-3\\"><article class=\\"eapp-surface-card p-4\\"><div class=\\"flex items-start justify-between gap-3\\"><div><p class=\\"text-sm font-medium eapp-text-tertiary\\">Total</p><p class=\\"mt-2 text-2xl font-semibold eapp-text-primary\\">0</p></div><span class=\\"eapp-primary-soft eapp-icon-tile\\"><span class=\\"eapp-primary-text\\">◆</span></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><article class=\\"eapp-primary-surface eapp-radius-panel border p-4\\"><p class=\\"text-sm font-semibold eapp-text-primary\\">Selected report</p><p class=\\"mt-1 text-sm eapp-text-tertiary\\">Only selected/current identity blocks use identity surface.</p></article></div></section></template><script setup>const { registerPageHeader } = usePageHeaderRegistry(); const { register: registerHeaderActions } = useHeaderActionRegistry(); registerPageHeader({ title: 'Reports', description: 'Operational report overview.', leadingIcon: 'lucide:bar-chart-3', gradient: 'none', variant: 'minimal' }); registerHeaderActions([{ id: 'refresh-reports', label: 'Refresh', icon: 'lucide:refresh-cw', color: 'neutral', variant: 'outline', onClick: () => {}, order: 80 }])</script>",
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
@@ -1581,26 +1597,14 @@ ensure_page_extension({
           'Use enfyra_menu.label, not title.',
           'Sensitive admin menus should include a permission condition at creation time.',
           'For page extensions, create the menu first with ensure_menu and pass its id to ensure_page_extension.',
-          'Call get_extension_theme_contract before writing or reviewing page/widget/global extension UI.',
-          'Call get_enfyra_required_knowledge before saving extension code and pass extensionAckKey as extensionKnowledgeAckKey.',
+          'Call get_extension_theme_contract before writing or reviewing page/widget/global extension UI; that tool is the authority for theme, color, layout, modal, drawer, and shell registry details.',
+          'Call get_enfyra_required_knowledge before saving extension code, pass globalRulesAckKey as globalRulesAckKey, and pass extensionAckKey as extensionKnowledgeAckKey.',
           'Page extensions must register the app-shell PageHeader with usePageHeaderRegistry instead of rendering a custom top header.',
-          'Use variant: "minimal" for operational pages unless a larger header is intentionally needed.',
-          'Do not put ordinary KPI cards in PageHeader.stats; render metrics in the extension body.',
           'Put page-level actions in useHeaderActionRegistry or useSubHeaderActionRegistry, destructure register first, then call it with one action or an array.',
-          'Page extensions should be full-bleed by default and responsive from the first version.',
-          'The extension root is already inside Enfyra admin page main; do not add root-level page padding.',
-          'Use eApp theme class tokens for panels, rows, badges, borders, controls, radius, and text. Generated extension templates should prefer eapp-surface-*, eapp-text-*, eapp-radius-*, eapp-divide-y, and eapp-primary-* over raw CSS variable utilities.',
-          'Treat primary color as runtime-configurable by the app color picker. For Nuxt UI components, choose color="primary" by semantic intent. For custom extension UI, decide whether each element is neutral surface, runtime-primary identity, or status: regular panels/KPI cards/list rows use eapp-surface-card/eapp-surface-muted/eapp-surface-hover/eapp-divide-y and eapp-text-* classes, while selected/current identity blocks, primary tiles, progress fills, primary icons, and primary CTA fills use eapp-primary-surface, eapp-primary-soft, eapp-primary-subtle, eapp-primary-solid, or eapp-primary-text so the color picker controls them. eapp-primary-surface supplies selected identity color but does not replace card chrome; keep border/radius classes on selected blocks.',
-          'Decision cases: normal decorative accents, feature icons, non-state tiles, active tabs, progress fills, selected segments, and primary actions use runtime primary/identity classes; true semantic states use their matching status colors such as error, warning, success, or info; large ordinary surfaces stay neutral and carry only small badges/icons for status; selected/current entity blocks may use eapp-primary-surface.',
-          'Pattern examples: KPI/metric cards should be eapp-surface-card with a small icon tile using eapp-primary-soft eapp-icon-tile; selected/current entity cards may use eapp-primary-surface; progress bars use eapp-surface-muted tracks plus eapp-primary-solid fills; list rows use eapp-surface-card/eapp-divide-y/eapp-surface-hover and only small chips inside; primary scope actions use UButton color="primary" variant="solid"; secondary actions use neutral variants.',
-          'Status colors belong only in UBadge/UAlert semantic colors or eapp-status-*-soft/text/border classes for badges, small icons, or short status text. Do not read --badge-* variables directly in extension templates. Do not color large panels, alert-like success blocks, KPI cards, list containers, or attention/reconciliation blocks green/yellow/red because of state; keep the block neutral and place the status badge/icon inside.',
-          'Use PageHeader gradient: "none" for generated operational pages unless the user explicitly asks for a decorative page accent; do not hardcode cyan/violet/purple/blue/green gradients.',
-          'For general card grids inside the shell, use md:grid-cols-2 xl:grid-cols-3 instead of lg:grid-cols-3 because the desktop sidebar leaves tablet-width content at 1024px.',
-          'Do not use Nuxt UI neutral semantic classes such as bg-default, text-muted, text-dimmed, border-default, or divide-default inside extension code; use eApp class tokens instead. Do not write text-[var(...)], bg-[var(...)], or border-[var(...)] in generated extension templates unless no class token exists for that exact primitive.',
-          'Do not pass ui.content: "eapp-surface-card" to UModal/CommonModal; modal content uses the app modal surface and caller content classes should only append z-index or width.',
-          'CommonModal and CommonDrawer own action-only footers through cancelAction, primaryAction, dangerAction, leadingActions, and footerHint. Pass action intent through props instead of styling footer buttons manually; cancelAction defaults to neutral outline, dangerAction is for irreversible destructive work, and Keep editing should use tone: "primary" in discard dialogs.',
-          'Use UTabs for page sections instead of custom tab bars so the app-level active/inactive indicators, spacing, focus rings, and theme contrast stay consistent.',
-          'Do not inject global CSS, create theme guards, redefine the app palette, or solve one extension by overriding the whole app shell.',
+          'Page extensions should be full-bleed and responsive from the first version; the extension root is already inside the Enfyra admin page main.',
+          'Render ordinary metrics and lists in the body, not PageHeader.stats, unless the user explicitly wants a compact overview header.',
+          'Use app theme tokens and Nuxt UI semantic colors by intent; do not hard-code concrete palettes or redefine the app palette inside extension code.',
+          'Use app-owned primitives such as UTabs, CommonModal, CommonDrawer, Widget, useMenuNotificationRegistry, and useAccountPanelRegistry when the workflow matches them.',
           'Keep list selection local and fetch detail rows only; do not refetch the whole list after a row click unless the list data changed.',
           'Page extension paths are admin app UI routes. Do not verify them with test_rest_endpoint against ENFYRA_API_URL unless inspect_route shows an API route with the same path.',
           'After saving, open Enfyra admin tabs should update through the server/Enfyra admin UI realtime reload contract; do not tell the user to refresh unless that contract is proven broken.',
@@ -1648,6 +1652,7 @@ ensure_widget_extension({
   description: "Report status summary cards",
   code: reportStatusWidgetCode,
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })
 
@@ -1657,6 +1662,7 @@ ensure_page_extension({
   menuId: "<reports-menu-id>",
   code: "<template><section class=\\"min-h-full w-full space-y-4\\"><Widget :id=\\"<report-status-widget-id>\\" :total=\\"totalReports\\" :rows=\\"reportRows\\" :open-details=\\"openReportDetails\\" @refresh=\\"refresh\\" /><Widget :id=\\"<report-table-widget-id>\\" :rows=\\"reportRows\\" @refresh=\\"refresh\\" /></section></template><script setup>const { registerPageHeader } = usePageHeaderRegistry(); registerPageHeader({ title: 'Reports', description: 'Operational report overview.', leadingIcon: 'lucide:bar-chart-3', gradient: 'none', variant: 'minimal' }); const totalReports = ref(0); const reportRows = ref([]); function refresh() {} function openReportDetails(row) { navigateTo('/data/report?filter=' + encodeURIComponent(JSON.stringify({ id: { _eq: row.id } }))) }</script>",
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
@@ -1751,6 +1757,7 @@ ensure_global_extension({
   description: "Registers the app-wide notification bell in the account panel",
   code: notificationBellCode,
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
@@ -1909,6 +1916,7 @@ ensure_global_extension({
   description: "Routes notification signals into account-panel and sidebar menu attention markers without polling destination lists",
   code: signalBridgeCode,
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
@@ -2166,7 +2174,8 @@ console.log(ok, requiredTerms.has('terms'), loaded, label, date)
         name: 'Install and use an app package in an extension',
         code: `install_package({
   name: "dayjs",
-  type: "App"
+  type: "App",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>"
 })
 
 // Then in extension code:

package/src/lib/mcp-instructions.js

@@ -29,7 +29,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Inspect narrowly. Use `inspect_table`, `inspect_route`, and `inspect_feature` for the table/route/feature being changed instead of loading broad metadata.',
     '- Load examples only when needed. Use `get_enfyra_examples` by category. Before extension UI, call `get_extension_theme_contract`; call `get_theme_class_reference` for exact eapp/Nuxt UI theme classes.',
     '- For server scripts, call `discover_script_contexts` before writing or reviewing handler/hook/flow/websocket/GraphQL logic.',
-    '- Before writing dynamic server or extension code, call `get_enfyra_required_knowledge` and pass the matching acknowledgement key into write tools.',
+    '- Before mutating metadata, schema, routes, permissions, menus, packages, cache state, dynamic code, or extension UI, call `get_enfyra_required_knowledge`, read the global rules, and pass `globalRulesAckKey` into write tools. Dynamic server code also requires `dynamicCodeAckKey`; extension code also requires `extensionAckKey`.',
     '- With non-root API tokens, call `get_permission_profile` before relying on admin helper tools or when debugging 403s. MCP admin helpers require ordinary route permissions for static admin routes such as `/admin/script/validate`, `/admin/test/run`, `/admin/flow/trigger/:id`, and `/admin/reload/*`.',
     '- Prefer the most specific business operation tool over raw metadata CRUD: `api_endpoint_workflow`, `create_api_endpoint`, `enable_route`, `add_route_methods`, `public_route_methods`, `set_table_graphql`, guard/permission/rule tools, websocket tools, flow tools, and `ensure_page_extension`/menu tools.',
     '- Before saving standalone dynamic script or extension code, call `validate_dynamic_script` or `validate_extension_code` unless the chosen ensure/update tool already validates the code.',