@enfyra/mcp-server 0.0.108 → 0.0.109

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.109",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

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: {
@@ -1528,6 +1545,7 @@ ensure_page_extension({
           '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.',
+          '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

@@ -29,7 +29,8 @@ 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. 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.',
     '- 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

@@ -565,6 +565,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';
@@ -1519,6 +1597,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 +1695,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 +1767,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.',

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) }] };