@enfyra/mcp-server 0.0.99 → 0.0.101

package/README.md

@@ -189,7 +189,7 @@ The MCP server includes safety guards for LLM callers:
 - Relation tools reject physical FK/junction names.
 - 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 `create_api_endpoint`, `publish_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`, `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.
 - Schema changes are serialized.
 - Destructive deletes return a preview before requiring `confirm=true`.
 

package/package.json

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

package/src/lib/mcp-examples.js

@@ -995,13 +995,13 @@ ensure_route_access({
         ],
       },
       {
-        name: 'Publish read-only route',
-        code: `publish_route_methods({
+        name: 'Make a read-only route public',
+        code: `public_route_methods({
   path: "/articles",
   methods: ["GET"]
 })`,
         notes: [
-          'Use publish_route_methods instead of raw enfyra_route updates; the tool resolves method ids and validates that GET is available.',
+          'Use public_route_methods instead of raw enfyra_route updates; the tool resolves method ids and validates that GET is available.',
           'publicMethods controls anonymous route access. Route permissions are not for public access.',
           'Route permissions apply when the method is not public.',
         ],

package/src/lib/mcp-instructions.js

@@ -29,7 +29,7 @@ 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: `create_api_endpoint`; route tools such as `add_route_methods`, `publish_route_methods`, and `unpublish_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`.',
+    '- 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 `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`.',
     '- 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.',
@@ -42,7 +42,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Dynamic repository reads use `filter`, not `where`: `@REPOS.table.find({ filter: {...} })`, `#table.find({ filter: {...} })`, and `exists(filter)`.',
     '- Use `enfyra_user` as the user table. Model record links as real relations using relation `propertyName` values, not physical FK fields like `userId`, `conversationId`, `senderId`, or `memberId` in generated DB code.',
     '- Do not call internal/no-route system tables such as `enfyra_column` or `enfyra_session` through generic CRUD. Use table/column/relation tools and route-backed tables discovered from metadata.',
-    '- Custom API paths use `create_api_endpoint` when a handler is needed. Use lower-level `create_route` without `mainTableId` only when intentionally creating a route shell; `create_table` is only for new persisted data.',
+    '- Custom API paths use `api_endpoint_workflow` when a handler is needed and the model should follow returned nextSteps. Use lower-level `create_route` without `mainTableId` only when intentionally creating a route shell; `create_table` is only for new persisted data.',
     '- For canonical table reads and RLS, preserve client-controlled query shape: do not override `@QUERY.fields`, `@QUERY.deep`, `@QUERY.sort`, `@QUERY.limit`, `@QUERY.page`, `@QUERY.meta`, `@QUERY.aggregate`, or `debugMode`. Merge only security filters into `@QUERY.filter`.',
     '- 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(...)`.',

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

@@ -208,6 +208,10 @@ async function reloadBestEffort(apiUrl, path) {
   }
 }
 
+function naturalPartialReload(reason) {
+  return { attempted: false, succeeded: true, reason };
+}
+
 async function validateDynamicScript(apiUrl, sourceCode, scriptLanguage = 'javascript') {
   const result = await fetchAPI(apiUrl, '/admin/script/validate', {
     method: 'POST',
@@ -408,7 +412,7 @@ async function ensureFlow(apiUrl, {
     isEnabled,
     description,
   });
-  const reload = await reloadBestEffort(apiUrl, '/admin/reload/flows');
+  const reload = naturalPartialReload('Flow metadata writes trigger the server partial reload contract; there is no dedicated flow reload endpoint.');
   return { action: 'flow_ensured', flow: { id: operation.id, name }, operation, reload };
 }
 
@@ -448,10 +452,307 @@ async function ensureFlowStep(apiUrl, {
     timeout,
     isEnabled,
   }, getId(flow)));
-  const reload = await reloadBestEffort(apiUrl, '/admin/reload/flows');
+  const reload = naturalPartialReload('Flow step writes trigger the server partial reload contract; there is no dedicated flow reload endpoint.');
   return { action: 'flow_step_ensured', flow: { id: getId(flow), name: flow.name }, step: { id: operation.id, key, type }, validation, operation, reload };
 }
 
+function normalizeEndpointAccess(anonymousAccess, makePublic) {
+  if (makePublic !== undefined) return makePublic ? 'public' : 'private';
+  return anonymousAccess || 'private';
+}
+
+function sourceMatches(existingHandler, sourceCode, scriptLanguage, timeout) {
+  if (!existingHandler) return false;
+  if (String(existingHandler.sourceCode ?? '') !== String(sourceCode ?? '')) return false;
+  if (scriptLanguage && String(existingHandler.scriptLanguage || 'javascript') !== String(scriptLanguage)) return false;
+  if (timeout !== undefined && Number(existingHandler.timeout) !== Number(timeout)) return false;
+  return true;
+}
+
+function step(status, id, title, detail = {}) {
+  return { id, title, status, ...detail };
+}
+
+async function resolveApiEndpointWorkflowState(apiUrl, opts) {
+  const normalizedPath = normalizeRestPath(opts.path);
+  const methodName = normalizeMethodName(opts.method);
+  const access = normalizeEndpointAccess(opts.anonymousAccess, opts.public);
+  const { methodMap, methodIdNameMap } = await getMethodContext(apiUrl);
+  const methodId = methodMap[methodName];
+  if (!methodId) throw new Error(`Unknown method "${methodName}". Valid methods: ${Object.keys(methodMap).sort().join(', ')}`);
+
+  const [routes, scriptValidation] = await Promise.all([
+    fetchAll(apiUrl, '/enfyra_route?limit=1000&fields=id,_id,path,isEnabled,description,availableMethods.*,publicMethods.*,mainTable.name'),
+    validateScriptSourceIfPresent(fetchAPI, apiUrl, 'enfyra_route_handler', {
+      sourceCode: opts.sourceCode,
+      scriptLanguage: opts.scriptLanguage || 'javascript',
+    }),
+  ]);
+
+  const route = routes.find((item) => item.path === normalizedPath) || null;
+  const routeId = getId(route);
+  const availableMethods = methodNamesFromRecords(route?.availableMethods || [], methodIdNameMap);
+  const publicMethods = methodNamesFromRecords(route?.publicMethods || [], methodIdNameMap);
+  const routeNeedsUpdate = !!route && (
+    route.isEnabled === false
+    || !availableMethods.includes(methodName)
+    || (access === 'public' && !publicMethods.includes(methodName))
+    || (access === 'private' && publicMethods.includes(methodName))
+    || (opts.description !== undefined && route.description !== opts.description)
+  );
+  const handler = route ? await findHandler(apiUrl, routeId, methodId) : null;
+  const handlerMatches = sourceMatches(handler, opts.sourceCode, opts.scriptLanguage || 'javascript', opts.timeout);
+  const handlerNeedsOverwrite = !!handler && !handlerMatches;
+
+  let permission = null;
+  let role = null;
+  let permissionMethods = [];
+  let permissionMissingMethods = [];
+  if (opts.roleName || opts.roleId || opts.allowedUserIds?.length) {
+    if (access === 'public') {
+      permissionMissingMethods = [];
+    } else if (!route) {
+      permissionMissingMethods = [methodName];
+    } else {
+      const permissions = await fetchRecords(apiUrl, 'enfyra_route_permission', {
+        route: { id: { _eq: routeId } },
+      }, 'id,_id,route.id,role.id,role.name,allowedUsers.id,methods.*', 1000);
+      role = await resolveRole(apiUrl, { roleId: opts.roleId, roleName: opts.roleName });
+      const allowedUserIds = (opts.allowedUserIds || []).map(String).sort();
+      permission = permissions.find((candidate) => {
+        const candidateRoleId = refId(candidate.role);
+        const candidateUserIds = (candidate.allowedUsers || []).map((item) => String(refId(item))).sort();
+        if (role && String(candidateRoleId) !== String(role.id)) return false;
+        if (!role && candidateRoleId !== null && candidateRoleId !== undefined) return false;
+        return allowedUserIds.length === candidateUserIds.length
+          && allowedUserIds.every((value, index) => value === candidateUserIds[index]);
+      }) || null;
+      permissionMethods = methodNamesFromRecords(permission?.methods || [], methodIdNameMap);
+      permissionMissingMethods = permissionMethods.includes(methodName) ? [] : [methodName];
+    }
+  }
+
+  const smokeTestRequested = opts.smokeTestQuery !== undefined || opts.smokeTestBody !== undefined;
+  const steps = [
+    route
+      ? step(routeNeedsUpdate ? 'pending' : 'completed', 'sync_route', 'Ensure route method and public access', {
+        routeId,
+        availableMethods,
+        publicMethods,
+        desiredAccess: access,
+      })
+      : step('pending', 'create_route', 'Create custom route', {
+        desiredAccess: access,
+      }),
+    handler
+      ? step(handlerNeedsOverwrite ? (opts.overwrite ? 'pending' : 'blocked') : 'completed', 'save_handler', 'Create or update route handler', {
+        handlerId: getId(handler),
+        reason: handlerNeedsOverwrite && !opts.overwrite ? 'Existing handler differs. Re-run with overwrite=true to update it.' : undefined,
+      })
+      : step(route ? 'pending' : 'waiting', 'save_handler', 'Create route handler', {
+        reason: route ? undefined : 'Route must exist first.',
+      }),
+  ];
+
+  if (opts.roleName || opts.roleId || opts.allowedUserIds?.length) {
+    steps.push(
+      access === 'public'
+        ? step('skipped', 'ensure_route_access', 'Ensure authenticated route access', {
+          reason: 'Method is public, so route permission is not required for anonymous access.',
+        })
+        : step(permissionMissingMethods.length ? (route ? 'pending' : 'waiting') : 'completed', 'ensure_route_access', 'Ensure authenticated route access', {
+          permissionId: getId(permission),
+          role,
+          allowedUserIds: opts.allowedUserIds || [],
+          methods: permissionMethods,
+          missingMethods: permissionMissingMethods,
+        }),
+    );
+  }
+
+  if (smokeTestRequested) {
+    const blockers = steps.filter((item) => ['pending', 'waiting', 'blocked'].includes(item.status));
+    steps.push(step(blockers.length ? 'waiting' : 'pending', 'smoke_test', 'Smoke-test the endpoint', {
+      reason: blockers.length ? 'Endpoint must be ready before smoke test.' : undefined,
+    }));
+  }
+
+  const firstRunnable = steps.find((item) => item.status === 'pending') || null;
+  const blocked = steps.find((item) => item.status === 'blocked') || null;
+
+  return {
+    endpoint: {
+      path: normalizedPath,
+      method: methodName,
+      anonymousAccess: access,
+      routeId,
+      handlerId: getId(handler),
+    },
+    methodId,
+    methodMap,
+    methodIdNameMap,
+    route,
+    handler,
+    role,
+    scriptValidation,
+    steps,
+    firstRunnable,
+    blocked,
+    nextSteps: blocked
+      ? [{ tool: 'api_endpoint_workflow', input: { path: normalizedPath, method: methodName, overwrite: true }, reason: blocked.reason }]
+      : firstRunnable
+        ? [{ tool: 'api_endpoint_workflow', input: { path: normalizedPath, method: methodName, apply: true }, stepId: firstRunnable.id }]
+        : [],
+  };
+}
+
+async function applyApiEndpointWorkflowStep(apiUrl, state, opts, stepId) {
+  const selectedStep = stepId
+    ? state.steps.find((item) => item.id === stepId)
+    : state.firstRunnable;
+  if (!selectedStep) return { action: 'noop', reason: 'No runnable step remains.' };
+  if (selectedStep.status !== 'pending') {
+    throw new Error(`Step "${selectedStep.id}" is ${selectedStep.status}, not pending.`);
+  }
+
+  const endpoint = state.endpoint;
+  if (selectedStep.id === 'create_route') {
+    const result = await fetchAPI(apiUrl, '/enfyra_route', {
+      method: 'POST',
+      body: JSON.stringify({
+        path: endpoint.path,
+        description: opts.description,
+        isEnabled: true,
+        availableMethods: [{ id: state.methodId }],
+        publicMethods: endpoint.anonymousAccess === 'public' ? [{ id: state.methodId }] : [],
+      }),
+    });
+    return { action: 'route_created', result, routeReload: await reloadRoutes(apiUrl) };
+  }
+
+  if (selectedStep.id === 'sync_route') {
+    const availableMethods = methodNamesFromRecords(state.route.availableMethods, state.methodIdNameMap);
+    const publicMethods = methodNamesFromRecords(state.route.publicMethods, state.methodIdNameMap);
+    const finalAvailable = uniqueMethodNames([...availableMethods, endpoint.method]);
+    const finalPublic = endpoint.anonymousAccess === 'public'
+      ? uniqueMethodNames([...publicMethods, endpoint.method])
+      : publicMethods.filter((method) => method !== endpoint.method);
+    const result = await fetchAPI(apiUrl, `/enfyra_route/${encodeURIComponent(String(endpoint.routeId))}`, {
+      method: 'PATCH',
+      body: JSON.stringify({
+        isEnabled: true,
+        availableMethods: resolveMethodRefs(state.methodMap, finalAvailable),
+        publicMethods: resolveMethodRefs(state.methodMap, finalPublic),
+        ...(opts.description !== undefined ? { description: opts.description } : {}),
+      }),
+    });
+    return { action: 'route_synced', result, routeReload: await reloadRoutes(apiUrl) };
+  }
+
+  if (selectedStep.id === 'save_handler') {
+    if (!endpoint.routeId) throw new Error('Route must exist before saving handler.');
+    const body = {
+      sourceCode: opts.sourceCode,
+      scriptLanguage: opts.scriptLanguage || 'javascript',
+      ...(opts.timeout !== undefined ? { timeout: opts.timeout } : {}),
+    };
+    if (state.handler) {
+      const result = await fetchAPI(apiUrl, `/enfyra_route_handler/${encodeURIComponent(String(getId(state.handler)))}`, {
+        method: 'PATCH',
+        body: JSON.stringify(body),
+      });
+      return { action: 'handler_updated', result, routeReload: await reloadRoutes(apiUrl) };
+    }
+    const result = await fetchAPI(apiUrl, '/enfyra_route_handler', {
+      method: 'POST',
+      body: JSON.stringify({
+        route: { id: endpoint.routeId },
+        method: { id: state.methodId },
+        ...body,
+      }),
+    });
+    return { action: 'handler_created', result, routeReload: await reloadRoutes(apiUrl) };
+  }
+
+  if (selectedStep.id === 'ensure_route_access') {
+    assertOneScope(opts);
+    const role = state.role || await resolveRole(apiUrl, { roleId: opts.roleId, roleName: opts.roleName });
+    const existing = state.steps.find((item) => item.id === 'ensure_route_access')?.permissionId
+      ? await findRecord(apiUrl, 'enfyra_route_permission', { id: { _eq: state.steps.find((item) => item.id === 'ensure_route_access').permissionId } }, 'id,_id,methods.*')
+      : null;
+    const existingMethods = methodNamesFromRecords(existing?.methods || [], state.methodIdNameMap);
+    const finalMethods = uniqueMethodNames([...existingMethods, endpoint.method]);
+    const body = {
+      isEnabled: true,
+      description: opts.routePermissionDescription,
+      methods: resolveMethodRefs(state.methodMap, finalMethods),
+      ...(role ? { role: { id: role.id } } : {}),
+      ...(opts.allowedUserIds?.length ? { allowedUsers: opts.allowedUserIds.map((id) => ({ id })) } : {}),
+    };
+    const result = existing
+      ? await fetchAPI(apiUrl, `/enfyra_route_permission/${encodeURIComponent(String(getId(existing)))}`, {
+        method: 'PATCH',
+        body: JSON.stringify(body),
+      })
+      : await fetchAPI(apiUrl, '/enfyra_route_permission', {
+        method: 'POST',
+        body: JSON.stringify({
+          route: { id: endpoint.routeId },
+          ...body,
+        }),
+      });
+    return { action: existing ? 'route_access_updated' : 'route_access_created', result, routeReload: await reloadRoutes(apiUrl) };
+  }
+
+  if (selectedStep.id === 'smoke_test') {
+    const query = parseJsonObjectArg('smokeTestQuery', opts.smokeTestQuery, {});
+    const queryParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null) queryParams.set(key, String(value));
+    }
+    const body = opts.smokeTestBody === undefined ? undefined : parseJsonObjectArg('smokeTestBody', opts.smokeTestBody, {});
+    const smokePath = `${endpoint.path}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+    const result = await fetchAPI(apiUrl, smokePath, {
+      method: endpoint.method,
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    return { action: 'smoke_test_passed', result };
+  }
+
+  throw new Error(`Unsupported workflow step: ${selectedStep.id}`);
+}
+
+async function runApiEndpointWorkflow(apiUrl, opts) {
+  let state = await resolveApiEndpointWorkflowState(apiUrl, opts);
+  const operations = [];
+  if (opts.apply || opts.applyAll) {
+    const maxSteps = opts.applyAll ? 10 : 1;
+    for (let i = 0; i < maxSteps; i += 1) {
+      if (state.blocked || !state.firstRunnable) break;
+      const operation = await applyApiEndpointWorkflowStep(apiUrl, state, opts, opts.stepId);
+      operations.push(operation);
+      if (!opts.applyAll) break;
+      state = await resolveApiEndpointWorkflowState(apiUrl, opts);
+    }
+  }
+  const latestState = operations.length ? await resolveApiEndpointWorkflowState(apiUrl, opts) : state;
+  return {
+    action: operations.length ? 'api_endpoint_workflow_advanced' : 'api_endpoint_workflow_planned',
+    endpoint: latestState.endpoint,
+    scriptValidation: latestState.scriptValidation,
+    steps: latestState.steps,
+    operations,
+    complete: latestState.steps.every((item) => ['completed', 'skipped'].includes(item.status)),
+    nextSteps: latestState.nextSteps,
+    cleanupHints: latestState.endpoint.routeId
+      ? [
+        `Preview delete route handler with delete_record({ tableName: "enfyra_route_handler", id: ${JSON.stringify(latestState.endpoint.handlerId)} }) before cleanup.`,
+        `Preview delete route with delete_record({ tableName: "enfyra_route", id: ${JSON.stringify(latestState.endpoint.routeId)} }) only when no longer needed.`,
+      ]
+      : [],
+  };
+}
+
 export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
   server.tool(
     'validate_dynamic_script',
@@ -566,12 +867,12 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
   );
 
   server.tool(
-    'publish_route_methods',
+    'public_route_methods',
     'Business operation: make existing route methods public/anonymous.',
     {
       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()).min(1).describe('HTTP method names to publish. They must already be available on the route.'),
+      methods: z.array(z.string()).min(1).describe('HTTP method names to make public. They must already be available on the route.'),
     },
     async ({ path, routeId, methods }) => jsonText(await updateRoutePublicMethods(ENFYRA_API_URL, {
       path,
@@ -582,7 +883,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
   );
 
   server.tool(
-    'replace_public_route_methods',
+    '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.'),
@@ -598,7 +899,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
   );
 
   server.tool(
-    'unpublish_route_methods',
+    'private_route_methods',
     'Business operation: make specific public route methods private again.',
     {
       path: z.string().optional().describe('Route path, e.g. /sum. Use either path or routeId.'),
@@ -613,12 +914,43 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     })),
   );
 
+  server.tool(
+    'api_endpoint_workflow',
+    [
+      'Step-by-step workflow for creating or updating a custom REST endpoint.',
+      'Use this when an LLM is building or changing endpoint behavior and should follow live nextSteps instead of guessing raw metadata mutations.',
+      'With apply=false it validates sourceCode, reads live route/handler/access state, and returns pending steps.',
+      'With apply=true it applies only the next pending step, then returns a fresh plan. With applyAll=true it advances all currently safe pending steps.',
+    ].join(' '),
+    {
+      path: z.string().describe('Custom route path, e.g. /sum. Must not be a full URL.'),
+      method: z.string().describe('HTTP method for the handler, e.g. GET or POST.'),
+      sourceCode: z.string().describe('Handler sourceCode. Use macros such as @QUERY, @BODY, @THROW400, @REPOS, @USER. Do not send compiledCode.'),
+      scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript').describe('Script language.'),
+      anonymousAccess: z.enum(['public', 'private']).optional().default('private').describe('public adds the method to publicMethods; private removes this method from publicMethods.'),
+      public: z.boolean().optional().describe('Compatibility alias for anonymousAccess. true means public, false means private.'),
+      roleId: z.union([z.string(), z.number()]).optional().describe('Optional role id for authenticated route permission.'),
+      roleName: z.string().optional().describe('Optional role name for authenticated route permission, e.g. user.'),
+      allowedUserIds: z.array(z.union([z.string(), z.number()])).optional().describe('Optional user id scope for authenticated route permission.'),
+      routePermissionDescription: z.string().optional().describe('Optional admin note for created/updated route permission.'),
+      description: z.string().optional().describe('Route description.'),
+      timeout: z.number().int().positive().optional().describe('Optional handler timeout in ms.'),
+      overwrite: z.boolean().optional().default(false).describe('Required to update an existing handler whose sourceCode/scriptLanguage/timeout differs.'),
+      smokeTestQuery: z.string().optional().describe('Optional query JSON object for a smoke test, e.g. {"a":"1","b":"2"}.'),
+      smokeTestBody: z.string().optional().describe('Optional body JSON object for a smoke test.'),
+      apply: z.boolean().optional().default(false).describe('false returns plan only; true applies exactly the next pending step.'),
+      applyAll: z.boolean().optional().default(false).describe('true applies all safe pending steps in order. Prefer apply=true for production changes.'),
+      stepId: z.string().optional().describe('Optional pending step id to apply. Omit to apply the next pending step.'),
+    },
+    async (input) => jsonText(await runApiEndpointWorkflow(ENFYRA_API_URL, input)),
+  );
+
   server.tool(
     'create_api_endpoint',
     [
       'Business operation: create or update a custom REST endpoint with a handler in one safe operation.',
       'Use this when the user asks for a new route/endpoint/API path that computes or orchestrates behavior, such as GET /sum or POST /webhook.',
-      'It creates the route without mainTableId, ensures the method is available, validates sourceCode, creates or overwrites the route handler, optionally publishes the method, reloads routes, and can smoke-test the endpoint.',
+      'It creates the route without mainTableId, ensures the method is available, validates sourceCode, creates or overwrites the route handler, optionally makes the method public, reloads routes, and can smoke-test the endpoint.',
       'Use table/schema tools separately when the user needs persisted data. This tool is for custom behavior endpoints.',
     ].join(' '),
     {
@@ -954,7 +1286,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
         ...(sourceCode !== undefined ? { sourceCode, scriptLanguage } : {}),
       };
       const operation = await createOrPatch(ENFYRA_API_URL, 'enfyra_websocket', existing, body);
-      const reload = await reloadBestEffort(ENFYRA_API_URL, '/admin/reload/websockets');
+      const reload = naturalPartialReload('Websocket metadata writes trigger the server partial reload contract; there is no dedicated websocket reload endpoint.');
       return jsonText({ action: 'websocket_gateway_ensured', gateway: { id: operation.id, path: normalizedPath }, validation, operation, reload });
     },
   );
@@ -991,7 +1323,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
         isEnabled,
         description,
       });
-      const reload = await reloadBestEffort(ENFYRA_API_URL, '/admin/reload/websockets');
+      const reload = naturalPartialReload('Websocket event writes trigger the server partial reload contract; there is no dedicated websocket reload endpoint.');
       return jsonText({ action: 'websocket_event_ensured', gateway: { id: getId(gateway), path: gateway.path }, eventName, validation, operation, reload });
     },
   );