@enfyra/mcp-server 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.1.4",
+  "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.',
@@ -1740,6 +1756,7 @@ 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.',
@@ -1895,11 +1912,12 @@ ensure_global_extension({
   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.',
+          '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.',
         ],
       },
@@ -1939,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.',
@@ -1993,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.',
@@ -2032,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",
@@ -2058,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.',
@@ -2089,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.',
         ],
       },
@@ -2215,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.',
         ],
@@ -2234,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.',
     };
@@ -2249,6 +2273,7 @@ export function getExamples(category) {
 
   return {
     category,
+    reasoningGuide: EXAMPLE_REASONING_GUIDE,
     ...entry,
   };
 }