@enfyra/mcp-server 0.0.109 → 0.0.110

package/package.json

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

package/src/lib/auth.js

@@ -8,13 +8,25 @@ let accessToken = null;
 let refreshToken = null;
 let tokenExpiry = null; // expTime từ server (milliseconds)
 let isRefreshing = false;
+let exchangePromise = null;
 
 // Config
 let API_URL = 'http://localhost:3000/api';
 let API_TOKEN = '';
 
-// Refresh buffer: refresh token 1 minute before expiry
-const TOKEN_REFRESH_BUFFER = 60000;
+const TOKEN_REFRESH_BUFFER = 20000;
+
+function normalizeExpiry(expTime) {
+  if (expTime == null) return Infinity;
+  if (typeof expTime === 'number') return expTime < 1_000_000_000_000 ? expTime * 1000 : expTime;
+  if (typeof expTime === 'string' && expTime.trim()) {
+    const numeric = Number(expTime);
+    if (Number.isFinite(numeric)) return numeric < 1_000_000_000_000 ? numeric * 1000 : numeric;
+    const parsed = Date.parse(expTime);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return Infinity;
+}
 
 /**
  * Initialize auth module with config
@@ -25,7 +37,7 @@ export function initAuth(apiUrl, apiToken = '') {
 }
 
 /**
- * Check if token needs refresh (expires within 1 minute)
+ * Check if token needs refresh (expires within the refresh buffer)
  */
 export function needsRefresh() {
   if (tokenExpiry === Infinity) return false;
@@ -60,27 +72,37 @@ export async function exchangeApiToken(url, apiToken) {
     throw new Error('API token required');
   }
 
-  console.error('[Auth] Exchanging API token...');
-  const response = await fetch(`${apiUrl}/auth/token/exchange`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ apiToken: token }),
-  });
+  if (exchangePromise) return exchangePromise;
 
-  if (!response.ok) {
-    throw new Error(`API token exchange failed: ${await response.text()}`);
-  }
+  exchangePromise = (async () => {
+    console.error('[Auth] Exchanging API token...');
+    const response = await fetch(`${apiUrl}/auth/token/exchange`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ apiToken: token }),
+    });
 
-  const data = await response.json();
-  accessToken = data.accessToken || data.access_token;
-  refreshToken = null;
-  tokenExpiry = data.expTime == null ? Infinity : data.expTime;
+    if (!response.ok) {
+      throw new Error(`API token exchange failed: ${await response.text()}`);
+    }
 
-  const expiryLabel = tokenExpiry === Infinity
-    ? 'no expiration'
-    : new Date(tokenExpiry).toISOString();
-  console.error(`[Auth] API token exchanged, access token expires at ${expiryLabel}`);
-  return accessToken;
+    const data = await response.json();
+    accessToken = data.accessToken || data.access_token;
+    refreshToken = null;
+    tokenExpiry = normalizeExpiry(data.expTime ?? data.exp_time ?? data.expiresAt ?? data.expires_at);
+
+    const expiryLabel = tokenExpiry === Infinity
+      ? 'no expiration'
+      : new Date(tokenExpiry).toISOString();
+    console.error(`[Auth] API token exchanged, access token expires at ${expiryLabel}`);
+    return accessToken;
+  })();
+
+  try {
+    return await exchangePromise;
+  } finally {
+    exchangePromise = null;
+  }
 }
 
 /**
@@ -119,7 +141,7 @@ export async function refreshAccessToken(url) {
     const data = await response.json();
     accessToken = data.accessToken || data.access_token;
     refreshToken = data.refreshToken || data.refresh_token;
-    tokenExpiry = data.expTime;
+    tokenExpiry = normalizeExpiry(data.expTime ?? data.exp_time ?? data.expiresAt ?? data.expires_at);
 
     console.error(`[Auth] Token refreshed, expires at ${new Date(tokenExpiry).toISOString()}`);
     return accessToken;

package/src/lib/mcp-examples.js

@@ -1539,12 +1539,15 @@ 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.',
           '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 theme tokens/classes for panels, rows, badges, borders, and text. Pair border/divide utilities with border-default or divide-[var(--border-default)] so light and dark themes stay consistent.',
+          '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.',
         ],

package/src/lib/mcp-instructions.js

@@ -27,7 +27,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- For a quick target/base sanity check, call `get_enfyra_api_context`; do not call broad discovery just to confirm which instance this MCP is connected to.',
     '- Discover before deciding. For architecture/capability questions call `discover_enfyra_system`; for DB/pk/runtime/cache context call `discover_runtime_context`; for filters/deep/sort/relation query shape call `discover_query_capabilities`. Run broad discovery tools sequentially, not in parallel.',
     '- 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. Before generating schemas, app connection code, OAuth, Socket.IO, handlers/hooks, flows, files, guards, permissions, or extensions, call `get_enfyra_examples` with the matching category.',
+    '- Load examples only when needed. Before generating schemas, app connection code, OAuth, Socket.IO, handlers/hooks, flows, files, guards, permissions, or extensions, call `get_enfyra_examples` with the matching category. Before extension UI work, call `get_extension_theme_contract` and follow the app-shell/theme/security contract.',
     '- For server scripts, call `discover_script_contexts` before writing or reviewing handler/hook/flow/websocket/GraphQL logic.',
     '- 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` for step-by-step endpoint work; `create_api_endpoint` only when a one-shot endpoint operation is clearly safe; route tools such as `enable_route`, `disable_route`, `delete_route`, `add_route_methods`, `public_route_methods`, and `private_route_methods`; `set_table_graphql`; `ensure_guard`; permission/rule tools; websocket tools; flow tools such as `ensure_manual_flow`, `ensure_scheduled_flow`, `choose_flow_step_tool`, and fixed-type flow step tools; and extension tools such as `ensure_menu`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension`.',

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

@@ -286,6 +286,40 @@ function jsonText(payload) {
   return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 }
 
+function getExtensionThemeContract() {
+  return {
+    action: 'extension_theme_contract',
+    useBefore: [
+      'Call this before writing or reviewing Enfyra admin page, widget, or global extension UI.',
+      'Then call validate_extension_code or an ensure_*_extension tool before saving.',
+    ],
+    layout: [
+      '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.',
+    ],
+    theme: [
+      'Use eApp theme tokens/classes, not hardcoded light or dark colors.',
+      'Use bg-default, bg-muted, text-highlighted, text-muted, border-default when available.',
+      'When using arbitrary CSS vars, prefer var(--surface-default), var(--surface-muted), var(--border-default), var(--text-primary), var(--text-secondary), and var(--text-tertiary).',
+      'Never use bare border/divide-y for panels or rows: pair them with border-default or divide-[var(--border-default)]. Avoid border-black, black, slate-only, gray-only, and dark-only palettes.',
+      'Status colors must remain readable in both themes; warning badges need high contrast text and a visible but not harsh border/background.',
+    ],
+    interaction: [
+      'Every mutating button needs pending/disabled state, success/error feedback, and must close or update its modal when the operation completes.',
+      'Do not refetch broad lists after selecting one row. Keep local selection state and fetch only the detail or mutation result needed.',
+      'Use bounded pagination for operational lists. Do not replace pagination with arbitrary fixed caps such as 30 or 50.',
+      'Customer-facing toasts must describe the operation. Do not surface raw job ids, flow ids, or worker ids.',
+    ],
+    security: [
+      'Decide route permission, owner scope, and field exposure before writing UI or backend logic.',
+      'UI checks are only guidance; handlers/hooks must independently enforce owner/root-admin authorization.',
+      'Use the most specific business route or MCP tool. Do not write directly to raw tables when a domain route exists.',
+    ],
+    compactExample: '<template><section class="min-h-full w-full space-y-4"><div class="rounded-lg border border-default bg-default"><div class="border-b border-default px-4 py-3"><h2 class="text-base font-semibold text-highlighted">Title</h2><p class="text-sm text-muted">Short operational context.</p></div><div class="divide-y divide-[var(--border-default)]"><button class="flex w-full items-center justify-between px-4 py-3 text-left hover:bg-muted/60"><span class="text-sm font-medium text-highlighted">Row</span><span class="text-sm text-muted">Open</span></button></div></div></section></template>',
+  };
+}
+
 function parseJsonObjectArg(name, value, fallback = {}) {
   if (value === undefined || value === null || value === '') return fallback;
   const parsed = typeof value === 'string' ? JSON.parse(value) : value;
@@ -979,6 +1013,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     [
       'Validate Enfyra admin extension code before saving it to enfyra_extension.',
       'Use this for Vue SFC page/widget/global extension code. It calls /enfyra_extension/preview and does not save anything.',
+      'Call get_extension_theme_contract first when generating or reviewing UI.',
     ].join(' '),
     {
       code: z.string().describe('Vue SFC or compiled extension bundle code.'),
@@ -990,6 +1025,13 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     }),
   );
 
+  server.tool(
+    'get_extension_theme_contract',
+    'Return the concise Enfyra admin extension UI/theme/security contract. Call before writing or reviewing extension UI.',
+    {},
+    async () => jsonText(getExtensionThemeContract()),
+  );
+
   server.tool(
     'set_table_graphql',
     'Business operation: enable or disable GraphQL for one table through enfyra_graphql, then reload GraphQL. REST route methods do not control GraphQL.',
@@ -1824,7 +1866,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
 
   server.tool(
     'ensure_page_extension',
-    'Business operation: create or update one page extension attached to an existing menu. Validates extension code before save.',
+    'Business operation: create or update one page extension attached to an existing menu. Validates extension code before save. Call get_extension_theme_contract first for UI work.',
     {
       name: z.string().describe('Extension unique name.'),
       code: z.string().describe('Vue SFC extension code.'),
@@ -1841,7 +1883,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
 
   server.tool(
     'ensure_global_extension',
-    'Business operation: create or update one global shell extension. Validates extension code before save and rejects menu coupling.',
+    'Business operation: create or update one global shell extension. Validates extension code before save and rejects menu coupling. Call get_extension_theme_contract first for UI work.',
     {
       name: z.string().describe('Extension unique name.'),
       code: z.string().describe('Vue SFC extension code.'),
@@ -1857,7 +1899,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
 
   server.tool(
     'ensure_widget_extension',
-    'Business operation: create or update one widget extension. Validates extension code before save and rejects menu coupling.',
+    'Business operation: create or update one widget extension. Validates extension code before save and rejects menu coupling. Call get_extension_theme_contract first for UI work.',
     {
       name: z.string().describe('Extension unique name.'),
       code: z.string().describe('Vue SFC extension code.'),