@enfyra/mcp-server 0.0.107 → 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`.
 
@@ -231,10 +231,14 @@ Do not create custom login/logout/me routes that manually set Enfyra token cooki
 
 The MCP server exposes tools for metadata discovery, examples, query/CRUD, method management, route lifecycle, route access audit/grant, routes, handlers, hooks, tables, columns, relations, cache reloads, logs, users, roles, packages, menus, extensions, scripts, flows, websocket, files, and `get_enfyra_api_context`.
 
-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`, `set_public_route_methods`, and `private_route_methods` for that access boundary.
+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.107",
+  "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,14 +29,15 @@ 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.',
     '',
     '### Core Contracts',
     '- Tool JSON responses use `responseFormat: "json+columnar-v1"`. Large arrays of objects may be encoded as `{ format: "columnar-v1", columns: [...], rows: [[...]], rowCount }` only when that is smaller than raw JSON; read each row value by matching `columns[index]` to `rows[n][index]`. Do not guess object keys inside `rows`. `compressionStats` estimates token savings and includes whether compression was applied; use it only when the user asks about savings.',
-    '- `query_table` and `get_all_routes` require explicit intent: pass `limit` for bounded reads or `all: true` for a complete list. Do not invent arbitrary limits such as 30 or 50.',
+    '- `query_table`, `get_all_routes`, and `get_all_tables` require explicit intent: pass `limit` for bounded reads or `all: true` for a complete list. Do not invent arbitrary limits such as 30 or 50.',
     '- Read tools are minimal by default. Pass explicit `fields`; use metadata inspection before guessing field/relation names. Field exclusion mode exists: `fields=-compiledCode`, and `fields=id,-compiledCode` still means all readable fields except `compiledCode`.',
     '- Mutations return ids/status by default. Re-read with `find_one_record` or `query_table` and explicit `fields` when the saved row matters.',
     '- Dynamic repository reads use `filter`, not `where`: `@REPOS.table.find({ filter: {...} })`, `#table.find({ filter: {...} })`, and `exists(filter)`.',
@@ -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/mutation-guards.js

@@ -72,7 +72,7 @@ export function rejectUnsafeRelationDefinitionPayload(tableName, payload) {
   if (forbidden.length > 0) {
     throw new Error(
       `Do not send physical FK/junction fields to enfyra_relation: ${forbidden.join(', ')}. ` +
-      'Use create_relation/add_relation with targetTable/type/propertyName; Enfyra derives physical columns.'
+      'Use create_relation with targetTable/type/propertyName; Enfyra derives physical columns.'
     );
   }
 }

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';
@@ -1047,22 +1125,6 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     })),
   );
 
-  server.tool(
-    'set_public_route_methods',
-    'Business operation: replace a route publicMethods list exactly.',
-    {
-      path: z.string().optional().describe('Route path, e.g. /sum. Use either path or routeId.'),
-      routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
-      methods: z.array(z.string()).describe('Exact HTTP method names that should be public. Use an empty array to make all methods private.'),
-    },
-    async ({ path, routeId, methods }) => jsonText(await updateRoutePublicMethods(ENFYRA_API_URL, {
-      path,
-      routeId,
-      methods,
-      mode: 'replace',
-    })),
-  );
-
   server.tool(
     'private_route_methods',
     'Business operation: make specific public route methods private again.',
@@ -1535,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.',
@@ -1611,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.',
@@ -1629,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/lib/table-tools.js

@@ -381,7 +381,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
           targetColumn: target,
           preservedColumnIds: beforeIds.filter((id) => id !== String(columnId)),
           destructive: true,
-          next: 'Call delete_column/remove_column again with confirm=true to drop the physical column and metadata.',
+          next: 'Call delete_column again with confirm=true to drop the physical column and metadata.',
         }, null, 2) }],
       };
     }
@@ -423,7 +423,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
           targetRelation: target,
           preservedRelationIds: beforeIds.filter((id) => id !== String(relationId)),
           destructive: true,
-          next: 'Call delete_relation/remove_relation again with confirm=true to drop relation metadata and any derived FK/junction structures.',
+          next: 'Call delete_relation again with confirm=true to drop relation metadata and any derived FK/junction structures.',
         }, null, 2) }],
       };
     }
@@ -699,18 +699,6 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     appendColumnToTable
   );
 
-  server.tool(
-    'add_column',
-    [
-      'Alias for create_column. Add a column to an existing table through the canonical enfyra_table cascade.',
-      'Use this for schema additions, including hidden secret fields with isPublished=false.',
-      'Reads full table metadata and skips non-persisted generated/derived column metadata without id/_id when rebuilding the table columns payload.',
-      'Run schema changes sequentially — migration locks DB per operation.',
-    ].join(' '),
-    columnCreateSchema,
-    appendColumnToTable
-  );
-
   // ─── UPDATE COLUMN ───
 
   server.tool(
@@ -788,18 +776,6 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     removeColumnFromTable
   );
 
-  server.tool(
-    'remove_column',
-    [
-      'Alias for delete_column. Remove a column through the canonical enfyra_table cascade.',
-      'This drops the physical column. Confirm destructive schema changes before calling.',
-      'Reads full table metadata and skips non-persisted generated/derived column metadata without id/_id when rebuilding the table columns payload.',
-      'Run schema changes sequentially — migration locks DB per operation.',
-    ].join(' '),
-    columnDeleteSchema,
-    removeColumnFromTable
-  );
-
   // ─── CREATE RELATION ───
 
   server.tool(
@@ -817,18 +793,6 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     appendRelationToTable
   );
 
-  server.tool(
-    'add_relation',
-    [
-      'Alias for create_relation. Add a relation through the canonical enfyra_table cascade.',
-      'sourceTableId and targetTableId may be table ids, exact table names, or aliases.',
-      'Use relation propertyName only; never provide physical FK or junction column names.',
-      'Run schema changes sequentially — migration locks DB per operation.',
-    ].join(' '),
-    relationCreateSchema,
-    appendRelationToTable
-  );
-
   // ─── DELETE RELATION ───
 
   server.tool(
@@ -844,13 +808,4 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     removeRelationFromTable
   );
 
-  server.tool(
-    'remove_relation',
-    [
-      'Alias for delete_relation. Remove a relation through the canonical enfyra_table cascade.',
-      'This can drop FK columns or junction tables. Confirm destructive schema changes before calling.',
-    ].join(' '),
-    relationDeleteSchema,
-    removeRelationFromTable
-  );
 }

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.'),
@@ -2468,137 +2624,6 @@ server.tool(
   },
 );
 
-server.tool(
-  'create_column_rule',
-  [
-    'Create a REST body validation rule for a table column.',
-    'Use inspect_table first to confirm validateBody, column type, and existing rules. Rule value is JSON; common shape is {"v": ...}.',
-  ].join(' '),
-  {
-    tableName: z.string().describe('Table name or alias'),
-    columnName: z.string().describe('Column name'),
-    ruleType: z.enum(['min', 'max', 'minLength', 'maxLength', 'pattern', 'format', 'minItems', 'maxItems', 'custom']).describe('Validation rule type'),
-    value: z.string().optional().describe('Rule payload JSON, e.g. {"v":10} or {"v":"email"}'),
-    message: z.string().optional().describe('Custom validation error message'),
-    description: z.string().optional().describe('Admin note'),
-    isEnabled: z.boolean().optional().default(true).describe('Enable the rule immediately'),
-  },
-  async ({ tableName, columnName, ruleType, value, message, description, isEnabled }) => {
-    const { tables } = await getMetadataTables();
-    const table = resolveTableOrThrow(tables, tableName);
-    const column = resolveFieldOrThrow(table, columnName, 'column');
-    const body = {
-      ruleType,
-      value: parseJsonArg(value, null),
-      message,
-      description,
-      isEnabled,
-      column: { id: getId(column) },
-    };
-    const result = await fetchAPI(ENFYRA_API_URL, '/enfyra_column_rule', {
-      method: 'POST',
-      body: JSON.stringify(body),
-    });
-    return { content: [{ type: 'text', text: `Column rule created for ${table.name}.${column.name}.\n${JSON.stringify(result, null, 2)}` }] };
-  },
-);
-
-server.tool(
-  'create_field_permission',
-  [
-    'Create a field permission for one column or relation.',
-    'Exactly one of columnName or relationName is required. Scope requires roleId or allowedUserIds. Conditions use the field permission condition DSL, not the full query DSL.',
-  ].join(' '),
-  {
-    tableName: z.string().describe('Table name or alias'),
-    columnName: z.string().optional().describe('Column name to protect'),
-    relationName: z.string().optional().describe('Relation propertyName to protect'),
-    action: z.enum(['read', 'create', 'update']).default('read').describe('Action this permission applies to'),
-    effect: z.enum(['allow', 'deny']).default('allow').describe('Allow or deny this field action'),
-    roleId: z.union([z.string(), z.number()]).optional().describe('Role id scope'),
-    allowedUserIds: z.array(z.union([z.string(), z.number()])).optional().describe('Specific user ids scope'),
-    condition: z.string().optional().describe('Optional condition JSON using field permission condition DSL'),
-    description: z.string().optional().describe('Admin note'),
-    isEnabled: z.boolean().optional().default(true).describe('Enable immediately'),
-  },
-  async ({ tableName, columnName, relationName, action, effect, roleId, allowedUserIds, condition, description, isEnabled }) => {
-    if (!!columnName === !!relationName) throw new Error('Provide exactly one of columnName or relationName');
-    if (!roleId && (!allowedUserIds || allowedUserIds.length === 0)) {
-      throw new Error('Provide roleId or allowedUserIds');
-    }
-    const { tables } = await getMetadataTables();
-    const table = resolveTableOrThrow(tables, tableName);
-    const body = {
-      isEnabled,
-      description,
-      action,
-      effect,
-      condition: parseJsonArg(condition, null),
-      ...(roleId ? { role: { id: roleId } } : {}),
-      ...(allowedUserIds?.length ? { allowedUsers: allowedUserIds.map((id) => ({ id })) } : {}),
-    };
-    if (columnName) {
-      body.column = { id: getId(resolveFieldOrThrow(table, columnName, 'column')) };
-    } else {
-      body.relation = { id: getId(resolveFieldOrThrow(table, relationName, 'relation')) };
-    }
-    const result = await fetchAPI(ENFYRA_API_URL, '/enfyra_field_permission', {
-      method: 'POST',
-      body: JSON.stringify(body),
-    });
-    return { content: [{ type: 'text', text: `Field permission created on ${table.name}.${columnName || relationName}.\n${JSON.stringify(result, null, 2)}` }] };
-  },
-);
-
-server.tool(
-  'create_route_permission',
-  [
-    'Create route access permission for a route and REST methods.',
-    'Use this when a non-root role/user should access an authenticated route. publicMethods are for public access; route permissions are for authenticated role/user access.',
-  ].join(' '),
-  {
-    path: z.string().optional().describe('Route path, e.g. /enfyra_user'),
-    routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
-    methods: z.array(z.string()).describe('REST method names this permission allows. Each value must exist in enfyra_method.name.'),
-    roleId: z.union([z.string(), z.number()]).optional().describe('Role id scope'),
-    allowedUserIds: z.array(z.union([z.string(), z.number()])).optional().describe('Specific user ids scope'),
-    description: z.string().optional().describe('Admin note'),
-    isEnabled: z.boolean().optional().default(true).describe('Enable immediately'),
-  },
-  async ({ path, routeId, methods, roleId, allowedUserIds, description, isEnabled }) => {
-    if (!path && !routeId) throw new Error('Provide path or routeId');
-    if (!roleId && (!allowedUserIds || allowedUserIds.length === 0)) {
-      throw new Error('Provide roleId or allowedUserIds');
-    }
-    const routes = await fetchAll('/enfyra_route?limit=1000');
-    const route = routes.find((item) => (
-      routeId ? sameId(getId(item), routeId) : item.path === normalizeRestPath(path)
-    ));
-    if (!route) throw new Error(`Route not found: ${routeId || path}`);
-    const methodMap = await getMethodMap();
-    const body = {
-      isEnabled,
-      description,
-      route: { id: getId(route) },
-      methods: resolveMethodIds(methodMap, methods),
-      ...(roleId ? { role: { id: roleId } } : {}),
-      ...(allowedUserIds?.length ? { allowedUsers: allowedUserIds.map((id) => ({ id })) } : {}),
-    };
-    const result = await fetchAPI(ENFYRA_API_URL, '/enfyra_route_permission', {
-      method: 'POST',
-      body: JSON.stringify(body),
-    });
-    const routeReload = await reloadRoutesResult();
-    return { content: [{ type: 'text', text: JSON.stringify({
-      action: 'created',
-      kind: 'route_permission',
-      route: route.path,
-      routeReload,
-      result,
-    }, null, 2) }] };
-  },
-);
-
 server.tool(
   'audit_route_access',
   [
@@ -2772,74 +2797,6 @@ server.tool(
   },
 );
 
-server.tool(
-  'create_guard',
-  [
-    'Create a metadata guard with optional rules for REST request gating.',
-    'Root guards attach to one route by path/routeId or globally with isGlobal. pre_auth runs before JWT and only has IP/route context; post_auth runs after auth and can use user id.',
-    'Rule types: rate_limit_by_ip, rate_limit_by_user, rate_limit_by_route, ip_whitelist, ip_blacklist. Rate limits use {"maxRequests":number,"perSeconds":number}; IP lists use {"ips":["127.0.0.1","10.0.0.0/24"]}.',
-    'Do not use rate_limit_by_user or userIds on pre_auth guards. Create risky global/IP whitelist guards disabled first, then inspect and test before enabling.',
-  ].join(' '),
-  {
-    name: z.string().describe('Guard name'),
-    position: z.enum(['pre_auth', 'post_auth']).default('pre_auth').describe('Execution position for root guard. pre_auth has only IP/route context; post_auth also has authenticated user id.'),
-    routeId: z.union([z.string(), z.number()]).optional().describe('Optional route id'),
-    path: z.string().optional().describe('Optional route path'),
-    methods: z.array(z.string()).optional().describe('Method names this guard applies to. Empty means all configured behavior for route/global.'),
-    combinator: z.enum(['and', 'or']).default('and').describe('How child guards/rules combine'),
-    priority: z.number().optional().default(0).describe('Lower runs first'),
-    isGlobal: z.boolean().optional().default(false).describe('Apply globally instead of one route'),
-    isEnabled: z.boolean().optional().default(false).describe('Enable immediately. Default false to avoid accidental lockout.'),
-    description: z.string().optional().describe('Admin note'),
-    rules: z.string().optional().describe('Optional rules JSON array: [{type, config, priority?, isEnabled?, description?, userIds?}]. Supported types: rate_limit_by_ip, rate_limit_by_user, rate_limit_by_route, ip_whitelist, ip_blacklist.'),
-  },
-  async ({ name, position, routeId, path, methods, combinator, priority, isGlobal, isEnabled, description, rules }) => {
-    let route = null;
-    if (!isGlobal && (routeId || path)) {
-      const routes = await fetchAll('/enfyra_route?limit=1000');
-      route = routes.find((item) => (
-        routeId ? sameId(getId(item), routeId) : item.path === normalizeRestPath(path)
-      ));
-      if (!route) throw new Error(`Route not found: ${routeId || path}`);
-    }
-    const methodMap = await getMethodMap();
-    const guardBody = {
-      name,
-      position,
-      combinator,
-      priority,
-      isGlobal,
-      isEnabled,
-      description,
-      ...(route ? { route: { id: getId(route) } } : {}),
-      ...(methods?.length ? { methods: resolveMethodIds(methodMap, methods) } : {}),
-    };
-    const guard = await fetchAPI(ENFYRA_API_URL, '/enfyra_guard', {
-      method: 'POST',
-      body: JSON.stringify(guardBody),
-    });
-    const ruleInputs = parseJsonArg(rules, []);
-    const createdRules = [];
-    for (const rule of ruleInputs) {
-      const ruleBody = {
-        type: rule.type,
-        config: rule.config,
-        priority: rule.priority ?? 0,
-        isEnabled: rule.isEnabled ?? true,
-        description: rule.description,
-        guard: { id: resultRecordId(guard) },
-        ...(Array.isArray(rule.userIds) && rule.userIds.length ? { users: rule.userIds.map((id) => ({ id })) } : {}),
-      };
-      createdRules.push(await fetchAPI(ENFYRA_API_URL, '/enfyra_guard_rule', {
-        method: 'POST',
-        body: JSON.stringify(ruleBody),
-      }));
-    }
-    await fetchAPI(ENFYRA_API_URL, '/admin/reload/guards', { method: 'POST' }).catch(() => {});
-    return { content: [{ type: 'text', text: `Guard created. Guard cache reloaded.\n${JSON.stringify({ guard, rules: createdRules }, null, 2)}` }] };
-  },
-);
-
 // Register table tools
 registerTableTools(server, ENFYRA_API_URL);
 registerPlatformOperationTools(server, ENFYRA_API_URL);
@@ -2933,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) }] };