@enfyra/mcp-server 0.0.108 → 0.0.110

package/README.md

@@ -191,7 +191,7 @@ The MCP server includes safety guards for LLM callers:
 - Relation tools reject physical FK/junction names and resolve table ids from exact table names or aliases before schema mutation.
 - Generated code should use relation property names such as `conversation`, `sender`, and `member` instead of physical FK fields such as `conversationId`, `senderId`, or `memberId`.
 - Custom route tools reject `mainTableId` unless the route is the canonical table route.
-- Platform operation tools such as `api_endpoint_workflow`, `create_api_endpoint`, `enable_route`, `disable_route`, `delete_route`, `public_route_methods`, `add_route_methods`, `set_table_graphql`, `ensure_guard`, `ensure_field_permission`, `ensure_column_rule`, `ensure_websocket_event`, `ensure_script_flow_step`, `ensure_menu`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension` resolve metadata ids and validate code before saving.
+- Platform operation tools such as `api_endpoint_workflow`, `create_api_endpoint`, `enable_route`, `disable_route`, `delete_route`, `public_route_methods`, `add_route_methods`, `set_table_graphql`, `ensure_guard`, `ensure_field_permission`, `ensure_column_rule`, `ensure_websocket_event`, `choose_flow_step_tool`, fixed-type flow step tools, `ensure_menu`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension` resolve metadata ids and validate code before saving.
 - Schema changes are serialized.
 - Destructive deletes return a preview before requiring `confirm=true`.
 
@@ -233,8 +233,12 @@ The MCP server exposes tools for metadata discovery, examples, query/CRUD, metho
 
 Routes have two separate controls. `isEnabled` controls runtime registration: disabled routes return `404`. Use `enable_route` and `disable_route` for this lifecycle. `publicMethods` controls anonymous access for enabled routes; use `public_route_methods` and `private_route_methods` for that access boundary.
 
+Admin app page paths and API paths are different surfaces. A page extension path such as `/cloud/projects/:id` is a UI route unless an enabled Enfyra API route with that exact path exists. Use `test_rest_endpoint` only for actual API routes under `ENFYRA_API_URL`; verify page extensions through the app URL/browser or extension/menu metadata.
+
 For authenticated route access, use `audit_route_access` before changing permissions and `ensure_route_access` to grant access by route path plus role/user. For production script edits, use `trace_metadata_usage`, `get_script_source`, and `patch_script_source` so changes are targeted, hash-checked, and validated.
 
 ## Security
 
+Treat permission and security as the first step for every change: decide public/private methods, authenticated route access, owner/tenant scope, and field exposure before creating handlers, flows, extensions, or UI.
+
 API calls use exchanged JWTs and Enfyra permissions are still enforced server-side. Keep `ENFYRA_API_TOKEN` out of committed config unless the project intentionally uses environment interpolation or another secret-management path.

package/package.json

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

@@ -1067,6 +1067,7 @@ ensure_route_access({
   description: "Authenticated users can list and create their own orders."
 })`,
         notes: [
+          'Start with the security boundary: choose public/private methods, role or user route access, owner/tenant scope, and field exposure before writing handler or UI logic.',
           'Use route permissions for authenticated access. The tool resolves role and method ids, validates the route available methods, merges existing methods, and reloads routes.',
           'Handlers or pre-hooks must still enforce owner or tenant scope; route permission only lets the request pass RoleGuard.',
           'Use publicMethods only for anonymous public access.',
@@ -1391,17 +1392,18 @@ return order && order.total > 1000`,
       {
         name: 'Split a provisioning workflow into focused steps',
         code: `[
-  { "key": "load_project", "stepOrder": 10, "type": "script" },
+  { "key": "load_project", "stepOrder": 10, "type": "query" },
   { "key": "reserve_capacity", "stepOrder": 20, "type": "script" },
-  { "key": "create_database_user", "stepOrder": 30, "type": "script" },
+  { "key": "create_database_user", "stepOrder": 30, "type": "http" },
   { "key": "apply_database_guardrails", "stepOrder": 40, "type": "script" },
-  { "key": "start_container", "stepOrder": 50, "type": "script" },
-  { "key": "apply_container_guardrails", "stepOrder": 60, "type": "script" },
-  { "key": "check_health", "stepOrder": 70, "type": "script" },
-  { "key": "finalize_project", "stepOrder": 80, "type": "script" }
+  { "key": "start_container", "stepOrder": 50, "type": "http" },
+  { "key": "check_health", "stepOrder": 60, "type": "http" },
+  { "key": "finalize_project", "stepOrder": 70, "type": "update" },
+  { "key": "write_audit_log", "stepOrder": 80, "type": "log" }
 ]`,
         notes: [
-          'Prefer operation-sized flow steps with clear keys over one large script that performs SSH, Docker, DB, API, email, and finalization work together.',
+          'Prefer the fixed-type flow step tool that matches each operation before falling back to script.',
+          'Use choose_flow_step_tool when the right step type is unclear.',
           'Each step should return only ids, booleans, status keys, or small counters that later steps need.',
           'When refactoring an existing flow, add or extract adjacent focused enfyra_flow_step rows instead of making an oversized sourceCode block longer.',
         ],
@@ -1418,6 +1420,21 @@ return order && order.total > 1000`,
           'Use public-safe URLs for HTTP steps.',
         ],
       },
+      {
+        name: 'Flow create/update/delete step configs',
+        code: `// ensure_create_flow_step
+{ "table": "todo", "data": { "title": "Review", "status": "open" } }
+
+// ensure_update_flow_step
+{ "table": "todo", "id": "@FLOW_PAYLOAD.todoId", "data": { "status": "done" } }
+
+// ensure_delete_flow_step
+{ "table": "todo", "id": "@FLOW_PAYLOAD.todoId" }`,
+        notes: [
+          'Use fixed CRUD flow step tools for single-record writes.',
+          'Use script only when a step must coordinate multiple records, compute complex data, or call packages.',
+        ],
+      },
     ],
   },
   files: {
@@ -1522,12 +1539,16 @@ 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,9 +27,10 @@ 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.',
-    '- 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`, and fixed-type flow step tools; and extension tools such as `ensure_menu`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension`.',
+    '- 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`.',
     '- 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.',
     '- For existing script-backed records, use `trace_metadata_usage` then `get_script_source`; edit with `patch_script_source` or `update_script_source` so source is hash-checked and validated.',
     '- Validate behavior with `test_rest_endpoint`, `run_admin_test`, `test_flow_step`, or the route-specific tool before claiming a dynamic feature works.',
@@ -47,6 +48,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Script source is `sourceCode`; `compiledCode` is generated and may differ textually because macros expand. Do not warn about source/compiled mismatch unless validation or runtime behavior proves the compiled artifact is stale.',
     '- For intentional user/domain errors in scripts use `@THROW400`-style helpers or `$ctx.$throw[...]`, not `throw new Error(...)`.',
     '- Destructive operations are preview-first. Do not pass `confirm=true` until the user explicitly approves.',
+    '- Treat permission and security as the first design step for any route, handler, flow, extension, or data surface: decide public/private methods, authenticated route access, owner/tenant scope, and field exposure before writing feature logic.',
+    '- Enfyra admin UI `usePermissions()` and backend RoleGuard both use route permissions: root admin passes; direct `allowedRoutePermissions` and role `routePermissions` grant route+method access. Use `audit_route_access` and `ensure_route_access` to inspect or grant these permissions.',
+    '- Route permissions only let authenticated users reach the route after RoleGuard; handlers, hooks, or RLS must still enforce record ownership and tenant/project scope.',
     '- Operator posture: act from these contracts plus live metadata. Do not turn expected implementation details into speculative warnings; ask only for new product/design decisions or genuine ambiguity.',
     '',
     '### App Connection Defaults',
@@ -61,6 +65,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '### Direct HTTP Mapping',
     '- Route-backed table CRUD is REST: `GET /<table>?...`, `POST /<table>`, `PATCH /<table>/<id>`, `DELETE /<table>/<id>`. There is no `GET /<table>/<id>`; use a filtered list with `limit=1` or `find_one_record`.',
     '- REST route lifecycle is controlled by `enfyra_route.isEnabled`: disabled routes are not registered at runtime and return 404. Use `enable_route`/`disable_route` instead of raw route PATCH. REST public access is controlled by route `publicMethods`; otherwise direct HTTP needs Bearer JWT plus route permissions. GraphQL table data requires Bearer auth and table GraphQL enablement; anonymous root/schema probes may still return a 200 without exposing table data.',
+    '- Admin app page/menu paths such as `/cloud/projects/:id` are UI routes, not Enfyra API endpoints unless an enabled `enfyra_route.path` with the same path exists. Use `test_rest_endpoint` only for paths that are actual API routes under `ENFYRA_API_URL`; verify page extensions through the app URL/browser or by reading the extension/menu metadata.',
     '',
     'When the user asks for details, fetch only the relevant live context or example category instead of relying on broad memorized rules.',
   ].join('\n');

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;
@@ -565,6 +599,84 @@ async function ensureFlowStep(apiUrl, {
   return { action: 'flow_step_ensured', flow: { id: getId(flow), name: flow.name }, step: { id: operation.id, key, type }, validation, operation, reload };
 }
 
+const FLOW_STEP_TOOL_GUIDANCE = [
+  {
+    tool: 'ensure_query_flow_step',
+    type: 'query',
+    when: 'Read/list records from one table without custom branching or transformation.',
+    config: { table: 'table_name', filter: {}, fields: 'id,name', limit: 20, sort: '-createdAt' },
+  },
+  {
+    tool: 'ensure_create_flow_step',
+    type: 'create',
+    when: 'Create one record in one table from static config or previous flow values.',
+    config: { table: 'table_name', data: { field: 'value' } },
+  },
+  {
+    tool: 'ensure_update_flow_step',
+    type: 'update',
+    when: 'Update one known record by id.',
+    config: { table: 'table_name', id: '@FLOW_PAYLOAD.id', data: { field: 'value' } },
+  },
+  {
+    tool: 'ensure_delete_flow_step',
+    type: 'delete',
+    when: 'Delete one known record by id.',
+    config: { table: 'table_name', id: '@FLOW_PAYLOAD.id' },
+  },
+  {
+    tool: 'ensure_http_flow_step',
+    type: 'http',
+    when: 'Call an external HTTP API.',
+    config: { url: 'https://example.com/api', method: 'POST', headers: {}, body: {}, timeout: 10000 },
+  },
+  {
+    tool: 'ensure_condition_flow_step',
+    type: 'condition',
+    when: 'Branch into true/false child steps based on JavaScript truthiness.',
+    sourceCode: 'return Boolean(@FLOW_PAYLOAD.enabled)',
+  },
+  {
+    tool: 'ensure_sleep_flow_step',
+    type: 'sleep',
+    when: 'Wait for a short bounded delay.',
+    config: { ms: 1000 },
+  },
+  {
+    tool: 'ensure_trigger_flow_step',
+    type: 'trigger_flow',
+    when: 'Trigger another flow as a child/orchestration step.',
+    config: { flowName: 'child-flow', payload: {} },
+  },
+  {
+    tool: 'ensure_log_flow_step',
+    type: 'log',
+    when: 'Record a small execution note for diagnostics.',
+    config: { message: 'Reached step_name' },
+  },
+  {
+    tool: 'ensure_script_flow_step',
+    type: 'script',
+    when: 'Use only when logic needs loops, multiple tables, crypto, package calls, non-trivial transforms, or runtime checks not covered by the atomic step tools.',
+    sourceCode: 'return { ok: true }',
+  },
+];
+
+function chooseFlowStepTool(intent) {
+  const text = String(intent || '').toLowerCase();
+  const hasAny = (patterns) => patterns.some((pattern) => pattern.test(text));
+  if (hasAny([/\bif\b/, /\belse\b/, /\bbranch\b/, /\bcondition\b/, /\bwhen\b/, /\bcheck\b/, /nếu/, /điều kiện/])) return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'condition');
+  if (hasAny([/\bhttp\b/, /\bapi\b/, /\bwebhook\b/, /\bfetch\b/, /\brequest\b/, /\bpost\b/, /\bget\b/, /\bcall\b/, /gọi api/])) return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'http');
+  if (hasAny([/\bsleep\b/, /\bwait\b/, /\bdelay\b/, /\bpause\b/, /chờ/, /đợi/])) return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'sleep');
+  if (hasAny([/\btrigger\b/, /\bchild flow\b/, /\banother flow\b/, /\bsubflow\b/, /flow khác/])) return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'trigger_flow');
+  if (hasAny([/\bdelete\b/, /\bremove\b/, /\bdestroy\b/, /xóa/, /xoá/])) return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'delete');
+  if (hasAny([/\bupdate\b/, /\bpatch\b/, /\bset\b/, /\bmark\b/, /\bchange\b/, /cập nhật/, /đánh dấu/])) return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'update');
+  if (hasAny([/\bcreate\b/, /\binsert\b/, /\badd\b/, /\bstore\b/, /\bsave\b/, /tạo/, /thêm/, /lưu/])) return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'create');
+  if (hasAny([/\blog\b/, /\bdebug\b/, /\btrace\b/, /ghi log/])) return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'log');
+  if (hasAny([/\bquery\b/, /\bfind\b/, /\blist\b/, /\bread\b/, /\bload\b/, /\bcount\b/, /\bsearch\b/, /đọc/, /tìm/, /liệt kê/])) return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'query');
+  return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'script');
+}
+
 function normalizeEndpointAccess(anonymousAccess, makePublic) {
   if (makePublic !== undefined) return makePublic ? 'public' : 'private';
   return anonymousAccess || 'private';
@@ -901,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.'),
@@ -912,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.',
@@ -1519,6 +1639,28 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     })),
   );
 
+  server.tool(
+    'choose_flow_step_tool',
+    'Dry-run helper: choose the most specific Enfyra flow step tool for one intended step before mutating flow metadata.',
+    {
+      intent: z.string().describe('Plain-language description of what this one flow step should do.'),
+    },
+    async ({ intent }) => {
+      const recommendation = chooseFlowStepTool(intent);
+      return jsonText({
+        action: 'flow_step_tool_recommended',
+        intent,
+        recommendation,
+        availableStepTools: FLOW_STEP_TOOL_GUIDANCE,
+        nextSteps: [
+          `Call ${recommendation.tool} with a stable key and order.`,
+          'Use ensure_script_flow_step only when the atomic tools cannot express the behavior.',
+          'After saving script or condition steps, use test_flow_step before relying on the flow.',
+        ],
+      });
+    },
+  );
+
   server.tool(
     'ensure_script_flow_step',
     'Business operation: create or update one script flow step. Use this for JavaScript/TypeScript flow logic instead of choosing type=script manually.',
@@ -1595,6 +1737,60 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     })),
   );
 
+  server.tool(
+    'ensure_create_flow_step',
+    'Business operation: create or update one create-record flow step. Use this for a single table insert instead of writing script code.',
+    {
+      flowName: z.string().optional().describe('Flow name. Use flowName or flowId.'),
+      flowId: z.union([z.string(), z.number()]).optional().describe('Flow id. Use flowName or flowId.'),
+      key: z.string().describe('Stable step key. Existing step with flow+key is updated.'),
+      config: z.string().describe('Step config JSON object: { "table": "...", "data": { ... } }.'),
+      order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
+      timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
+      isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+    },
+    async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
+      ...input,
+      type: 'create',
+    })),
+  );
+
+  server.tool(
+    'ensure_update_flow_step',
+    'Business operation: create or update one update-record flow step. Use this for a single table update by id instead of writing script code.',
+    {
+      flowName: z.string().optional().describe('Flow name. Use flowName or flowId.'),
+      flowId: z.union([z.string(), z.number()]).optional().describe('Flow id. Use flowName or flowId.'),
+      key: z.string().describe('Stable step key. Existing step with flow+key is updated.'),
+      config: z.string().describe('Step config JSON object: { "table": "...", "id": "...", "data": { ... } }.'),
+      order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
+      timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
+      isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+    },
+    async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
+      ...input,
+      type: 'update',
+    })),
+  );
+
+  server.tool(
+    'ensure_delete_flow_step',
+    'Business operation: create or update one delete-record flow step. Use this for a single table delete by id instead of writing script code.',
+    {
+      flowName: z.string().optional().describe('Flow name. Use flowName or flowId.'),
+      flowId: z.union([z.string(), z.number()]).optional().describe('Flow id. Use flowName or flowId.'),
+      key: z.string().describe('Stable step key. Existing step with flow+key is updated.'),
+      config: z.string().describe('Step config JSON object: { "table": "...", "id": "..." }.'),
+      order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
+      timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
+      isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+    },
+    async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
+      ...input,
+      type: 'delete',
+    })),
+  );
+
   server.tool(
     'ensure_sleep_flow_step',
     'Business operation: create or update one sleep/wait flow step. Use this for delays instead of choosing type=sleep manually.',
@@ -1613,6 +1809,24 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     })),
   );
 
+  server.tool(
+    'ensure_log_flow_step',
+    'Business operation: create or update one log flow step. Use this for lightweight execution diagnostics instead of script code.',
+    {
+      flowName: z.string().optional().describe('Flow name. Use flowName or flowId.'),
+      flowId: z.union([z.string(), z.number()]).optional().describe('Flow id. Use flowName or flowId.'),
+      key: z.string().describe('Stable step key. Existing step with flow+key is updated.'),
+      config: z.string().describe('Step config JSON object: { "message": "..." }.'),
+      order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
+      timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
+      isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+    },
+    async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
+      ...input,
+      type: 'log',
+    })),
+  );
+
   server.tool(
     'ensure_trigger_flow_step',
     'Business operation: create or update one child-flow trigger step. Use this for flow-to-flow orchestration instead of choosing type=trigger_flow manually.',
@@ -1652,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.'),
@@ -1669,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.'),
@@ -1685,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.'),

package/src/mcp-server-entry.mjs

@@ -114,6 +114,73 @@ const FILTER_OPERATORS = [
   '_not',
 ];
 
+const DEFAULT_ME_PERMISSION_FIELDS = [
+  'id',
+  'email',
+  'isRootAdmin',
+  'role.id',
+  'role.name',
+  'role.routePermissions.id',
+  'role.routePermissions.isEnabled',
+  'role.routePermissions.methods.id',
+  'role.routePermissions.methods.name',
+  'role.routePermissions.route.id',
+  'role.routePermissions.route.path',
+  'role.routePermissions.allowedUsers.id',
+  'allowedRoutePermissions.id',
+  'allowedRoutePermissions.isEnabled',
+  'allowedRoutePermissions.methods.id',
+  'allowedRoutePermissions.methods.name',
+  'allowedRoutePermissions.route.id',
+  'allowedRoutePermissions.route.path',
+  'allowedRoutePermissions.allowedUsers.id',
+];
+
+const MCP_PERMISSION_REQUIREMENTS = [
+  {
+    area: 'script validation',
+    tools: ['validate_dynamic_script', 'create_handler', 'create_pre_hook', 'create_post_hook', 'patch_script_source', 'update_script_source', 'ensure_script_flow_step', 'ensure_condition_flow_step', 'ensure_websocket_event'],
+    route: '/admin/script/validate',
+    methods: ['POST'],
+  },
+  {
+    area: 'flow and websocket test runner',
+    tools: ['run_admin_test', 'test_flow_step'],
+    route: '/admin/test/run',
+    methods: ['POST'],
+  },
+  {
+    area: 'manual flow trigger',
+    tools: ['trigger_flow'],
+    route: '/admin/flow/trigger/:id',
+    methods: ['POST'],
+  },
+  {
+    area: 'route cache reload',
+    tools: ['reload_routes', 'enable_route', 'disable_route', 'delete_route', 'public_route_methods', 'private_route_methods', 'add_route_methods', 'replace_route_methods', 'remove_route_methods', 'ensure_route_access'],
+    route: '/admin/reload/routes',
+    methods: ['POST'],
+  },
+  {
+    area: 'metadata cache reload',
+    tools: ['reload_metadata'],
+    route: '/admin/reload/metadata',
+    methods: ['POST'],
+  },
+  {
+    area: 'GraphQL cache reload',
+    tools: ['reload_graphql', 'set_table_graphql'],
+    route: '/admin/reload/graphql',
+    methods: ['POST'],
+  },
+  {
+    area: 'full cache reload',
+    tools: ['reload_all'],
+    route: '/admin/reload',
+    methods: ['POST'],
+  },
+];
+
 const FIELD_PERMISSION_CONDITION_OPERATORS = [
   '_eq',
   '_neq',
@@ -302,6 +369,94 @@ function resultRecordId(result) {
   return getId(firstDataRecord(result));
 }
 
+function normalizePermissionRoute(routePath) {
+  const value = String(routePath || '').trim();
+  return value.startsWith('/') ? value : `/${value}`;
+}
+
+function methodNames(permission) {
+  return normalizeMethodNames((permission?.methods || []).map((method) => method?.name || method));
+}
+
+function permissionAllowedUserIds(permission) {
+  return (permission?.allowedUsers || []).map((user) => String(refId(user))).filter(Boolean);
+}
+
+function permissionMatchesUser(permission, userId) {
+  const allowed = permissionAllowedUserIds(permission);
+  if (!allowed.length) return true;
+  return userId ? allowed.includes(String(userId)) : false;
+}
+
+function directPermissionMatchesUser(permission, userId) {
+  const allowed = permissionAllowedUserIds(permission);
+  return userId ? allowed.includes(String(userId)) : false;
+}
+
+function userHasRoutePermission(user, routePath, method) {
+  if (!user) return false;
+  if (user.isRootAdmin) return true;
+
+  const normalizedRoute = normalizePermissionRoute(routePath);
+  const normalizedMethod = String(method || '').toUpperCase();
+  const userId = getId(user);
+  const directPermissions = user.allowedRoutePermissions || [];
+  const rolePermissions = user.role?.routePermissions || [];
+
+  const matchesRouteAndMethod = (permission) => (
+    permission?.isEnabled !== false
+    && permission?.route?.path === normalizedRoute
+    && methodNames(permission).includes(normalizedMethod)
+  );
+
+  return directPermissions.some((permission) => (
+    matchesRouteAndMethod(permission)
+    && directPermissionMatchesUser(permission, userId)
+  )) || rolePermissions.some((permission) => (
+    matchesRouteAndMethod(permission)
+    && permissionMatchesUser(permission, userId)
+  ));
+}
+
+function summarizePermissionProfile(user) {
+  const requirements = MCP_PERMISSION_REQUIREMENTS.map((requirement) => {
+    const methods = requirement.methods.map((method) => ({
+      method,
+      allowed: userHasRoutePermission(user, requirement.route, method),
+    }));
+    return {
+      ...requirement,
+      methods,
+      allowed: methods.every((item) => item.allowed),
+    };
+  });
+
+  return {
+    user: user ? {
+      id: getId(user),
+      email: user.email || null,
+      isRootAdmin: !!user.isRootAdmin,
+      role: user.role ? {
+        id: getId(user.role),
+        name: user.role.name || null,
+      } : null,
+    } : null,
+    permissionModel: {
+      sameAsAdminUi: 'Mirrors Enfyra admin usePermissions(): root admin passes; otherwise direct allowedRoutePermissions are checked before role.routePermissions.',
+      publicMethods: 'Anonymous REST access is controlled by route.publicMethods; this profile only reports authenticated route permissions for the configured token.',
+    },
+    mcpRequirements: requirements,
+    missingRequirements: requirements
+      .filter((item) => !item.allowed)
+      .map((item) => ({
+        area: item.area,
+        route: item.route,
+        methods: item.methods.filter((method) => !method.allowed).map((method) => method.method),
+        tools: item.tools,
+      })),
+  };
+}
+
 function parseJsonArg(value, fallback = undefined) {
   if (value === undefined || value === null || value === '') return fallback;
   return JSON.parse(value);
@@ -2130,6 +2285,7 @@ server.tool(
   [
     'Execute a real REST request against the configured Enfyra API base.',
     'Use this after inspecting a route or changing handlers/hooks/guards. Pass paths like /enfyra_table?limit=1, not external URLs.',
+    'Do not use this for admin app page/menu routes such as /cloud/projects/:id unless inspect_route confirms an API route with that exact path.',
   ].join(' '),
   {
     method: z.string().optional().default('GET').describe('HTTP method name. Must exist in enfyra_method.name for Enfyra route-backed calls.'),
@@ -2734,6 +2890,22 @@ server.tool('get_current_user', 'Get current authenticated user info', {}, async
   return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
 });
 
+server.tool(
+  'get_permission_profile',
+  [
+    'Inspect the current token permission profile using the same route-permission model as Enfyra admin UI usePermissions().',
+    'Use this before debugging 403s or before relying on admin helper tools with a non-root API token.',
+    'Reports which MCP tool groups need route permissions such as /admin/script/validate, /admin/test/run, /admin/flow/trigger/:id, and reload endpoints.',
+  ].join(' '),
+  {},
+  async () => {
+    const fields = DEFAULT_ME_PERMISSION_FIELDS.join(',');
+    const result = await fetchAPI(ENFYRA_API_URL, `/me?fields=${encodeURIComponent(fields)}`);
+    const user = firstDataRecord(result);
+    return jsonContent(summarizePermissionProfile(user));
+  },
+);
+
 server.tool('get_all_roles', 'Get all role definitions', {}, async () => {
   const result = await fetchAPI(ENFYRA_API_URL, '/enfyra_role?limit=100');
   return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };