@enfyra/mcp-server 0.0.104 → 0.0.106

package/README.md

@@ -169,6 +169,7 @@ For normal apps and demos, enter the app/admin URL such as `http://localhost:300
 Use `get_enfyra_examples` from the MCP tool list when asking an LLM to generate implementation patterns. It returns focused examples for:
 
 - SSR app auth and proxy setup
+- OAuth provider setup
 - schema, columns, relations, indexes, and validation
 - query filters, sorting, fields, deep relations, and aggregates
 - handlers, hooks, permissions, and RLS
@@ -190,7 +191,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 `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.
+- 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.
 - Schema changes are serialized.
 - Destructive deletes return a preview before requiring `confirm=true`.
 
@@ -228,7 +229,9 @@ Do not create custom login/logout/me routes that manually set Enfyra token cooki
 
 ## Tool Summary
 
-The MCP server exposes tools for metadata discovery, examples, query/CRUD, method management, 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`.
+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.
 
 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.
 

package/package.json

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

package/src/lib/mcp-examples.js

@@ -457,6 +457,84 @@ window.location.href = url.toString()`,
       },
     ],
   },
+  'oauth-setup': {
+    title: 'OAuth provider setup',
+    useWhen: 'Use when configuring Google or another OAuth provider for an Enfyra-backed app.',
+    examples: [
+      {
+        name: 'Google OAuth setup workflow',
+        code: `// 1. Ask for the public app/admin URL, not the API URL.
+// Example input from the user:
+const appUrl = "https://demo.enfyra.io"
+
+// 2. Derive the Enfyra API base and provider callback.
+const apiBase = appUrl.replace(/\\/$/, "") + "/api"
+const googleCallbackUrl = apiBase + "/auth/google/callback"
+
+// 3. Tell the user to paste this exact value into Google Cloud Console:
+// APIs & Services -> Credentials -> OAuth 2.0 Client -> Authorized redirect URIs
+// https://demo.enfyra.io/api/auth/google/callback
+
+// 4. After the user provides Google client id/secret, save Enfyra config:
+create_record({
+  tableName: "enfyra_oauth_config",
+  body: JSON.stringify({
+    provider: "google",
+    clientId: "<google-client-id>",
+    clientSecret: "<google-client-secret>",
+    redirectUri: googleCallbackUrl,
+    isEnabled: true
+  })
+})`,
+        notes: [
+          'Ask for the app/admin URL such as https://demo.enfyra.io; derive the API base by appending /api.',
+          'The provider callback is {appUrl}/api/auth/{provider}/callback and must exactly match the Authorized redirect URI in Google Cloud Console.',
+          'Do not ask the user to choose or type the callback URL manually once the app URL is known; compute it and show the exact value to paste.',
+          'The OAuth callback is the Enfyra provider callback, not the final app page.',
+          'When starting OAuth from a browser app, use the same-origin proxy route with redirect and cookieBridgePrefix as shown in ssr-app-auth examples.',
+        ],
+      },
+      {
+        name: 'Browser OAuth start URL after setup',
+        code: `const returnUrl = new URL("/dashboard", window.location.origin)
+const oauthUrl = new URL("/enfyra/auth/google", window.location.origin)
+oauthUrl.searchParams.set("redirect", returnUrl.toString())
+oauthUrl.searchParams.set("cookieBridgePrefix", "/enfyra")
+window.location.href = oauthUrl.toString()`,
+        notes: [
+          'This is the browser start URL through the app proxy; it is different from the Google Authorized redirect URI.',
+          'After Enfyra finishes the Google callback, it bridges cookies through /enfyra/auth/set-cookies and returns to the absolute redirect URL.',
+          'After return, call /enfyra/me to load the user.',
+        ],
+      },
+      {
+        name: 'Update an existing Google OAuth config',
+        code: `const existing = await query_table({
+  tableName: "enfyra_oauth_config",
+  filter: JSON.stringify({ provider: { _eq: "google" } }),
+  fields: ["id", "provider", "redirectUri", "isEnabled"],
+  limit: 1
+})
+
+// If a row exists, update it instead of creating a duplicate.
+update_record({
+  tableName: "enfyra_oauth_config",
+  id: "<existing-config-id>",
+  body: JSON.stringify({
+    clientId: "<google-client-id>",
+    clientSecret: "<google-client-secret>",
+    redirectUri: "https://demo.enfyra.io/api/auth/google/callback",
+    isEnabled: true
+  })
+})`,
+        notes: [
+          'Inspect first so setup is idempotent.',
+          'Use the current system table name enfyra_oauth_config.',
+          'Never expose the client secret back in app code or documentation.',
+        ],
+      },
+    ],
+  },
   'schema-relations': {
     title: 'Tables, columns, relations, cascade, and indexes',
     useWhen: 'Use when creating or changing persisted data models.',

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: `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`.',
+    '- 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`.',
     '- 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.',
@@ -51,7 +51,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### App Connection Defaults',
     '- Generated Nuxt/Next/SSR apps should use a same-origin proxy such as `/enfyra/**` to the Enfyra API. Browser code calls `/enfyra/login`, `/enfyra/me`, `/enfyra/logout`, and `/enfyra/<table>`; it should not store JWTs.',
-    '- OAuth starts through the same proxy prefix with `redirect=<absoluteReturnUrl>` and `cookieBridgePrefix=/enfyra`. OAuth setup details live in `get_enfyra_examples({ category: "ssr-app-auth" })`.',
+    '- OAuth starts through the same proxy prefix with `redirect=<absoluteReturnUrl>` and `cookieBridgePrefix=/enfyra`. Provider setup details live in `get_enfyra_examples({ category: "oauth-setup" })`.',
     '- Socket.IO browser clients connect to the gateway namespace, e.g. `io("/chat", { path: "/socket.io", withCredentials: true })`, while the app proxies `/socket.io/**` to Enfyra `/ws/socket.io/**`.',
     '',
     '### Dynamic Script Surface',
@@ -60,7 +60,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 public access is controlled by route `publicMethods`; otherwise direct HTTP needs Bearer JWT plus route permissions. GraphQL requires Bearer auth and table GraphQL enablement.',
+    '- 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 requires Bearer auth and table GraphQL enablement.',
     '',
     '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

@@ -164,6 +164,115 @@ async function updateRoutePublicMethods(apiUrl, { path, routeId, methods, mode }
   };
 }
 
+async function setRouteEnabled(apiUrl, { path, routeId, isEnabled }) {
+  const { route } = await resolveRoute(apiUrl, { path, routeId });
+  const before = route?.isEnabled !== false;
+  if (before === isEnabled) {
+    return {
+      action: isEnabled ? 'route_already_enabled' : 'route_already_disabled',
+      route: { id: getId(route), path: route.path },
+      before: { isEnabled: before },
+      after: { isEnabled },
+      runtimeBehavior: isEnabled ? 'Enabled routes are registered at runtime.' : 'Disabled routes are not registered at runtime and return 404.',
+      routeReload: { attempted: false, succeeded: true, reason: 'No route lifecycle change was needed.' },
+    };
+  }
+
+  const result = await fetchAPI(apiUrl, `/enfyra_route/${encodeURIComponent(String(getId(route)))}`, {
+    method: 'PATCH',
+    body: JSON.stringify({ isEnabled }),
+  });
+  const routeReload = await reloadRoutes(apiUrl);
+  return {
+    action: isEnabled ? 'route_enabled' : 'route_disabled',
+    route: { id: getId(route), path: route.path },
+    before: { isEnabled: before },
+    after: { isEnabled },
+    runtimeBehavior: isEnabled ? 'The route should now be registered at runtime.' : 'The route should now return 404 because disabled routes are not registered at runtime.',
+    result,
+    routeReload,
+  };
+}
+
+async function fetchRouteDependencies(apiUrl, routeId) {
+  const routeFilter = filterQuery({ route: { id: { _eq: routeId } } });
+  const routeIdFilter = filterQuery({ routeId: { _eq: routeId } });
+  const [handlers, permissions, preHooks, postHooks, guards] = await Promise.all([
+    fetchAll(apiUrl, `/enfyra_route_handler?filter=${routeIdFilter}&fields=id,_id,routeId,method.name&limit=0`),
+    fetchAll(apiUrl, `/enfyra_route_permission?filter=${routeFilter}&fields=id,_id,route.id,role.name,isEnabled&limit=0`),
+    fetchAll(apiUrl, `/enfyra_pre_hook?filter=${routeFilter}&fields=id,_id,route.id,name,isEnabled&limit=0`),
+    fetchAll(apiUrl, `/enfyra_post_hook?filter=${routeFilter}&fields=id,_id,route.id,name,isEnabled&limit=0`),
+    fetchAll(apiUrl, `/enfyra_guard?filter=${routeFilter}&fields=id,_id,route.id,name,isEnabled&limit=0`),
+  ]);
+  return { handlers, permissions, preHooks, postHooks, guards };
+}
+
+function summarizeRouteDependencies(dependencies) {
+  return {
+    handlers: dependencies.handlers.map((item) => ({ id: getId(item), method: item?.method?.name || null })),
+    permissions: dependencies.permissions.map((item) => ({ id: getId(item), role: item?.role?.name || null, isEnabled: item?.isEnabled !== false })),
+    preHooks: dependencies.preHooks.map((item) => ({ id: getId(item), name: item?.name || null, isEnabled: item?.isEnabled !== false })),
+    postHooks: dependencies.postHooks.map((item) => ({ id: getId(item), name: item?.name || null, isEnabled: item?.isEnabled !== false })),
+    guards: dependencies.guards.map((item) => ({ id: getId(item), name: item?.name || null, isEnabled: item?.isEnabled !== false })),
+  };
+}
+
+async function deleteRows(apiUrl, tableName, rows) {
+  const deleted = [];
+  for (const row of rows) {
+    const id = getId(row);
+    if (id === null || id === undefined) continue;
+    await fetchAPI(apiUrl, `/${tableName}/${encodeURIComponent(String(id))}`, { method: 'DELETE' });
+    deleted.push(id);
+  }
+  return deleted;
+}
+
+async function deleteRoute(apiUrl, { path, routeId, expectedPath, confirm }) {
+  const { route } = await resolveRoute(apiUrl, { path, routeId });
+  if (expectedPath && route.path !== normalizeRestPath(expectedPath)) {
+    throw new Error(`Route path mismatch: resolved ${route.path}, expected ${normalizeRestPath(expectedPath)}.`);
+  }
+
+  const dependencies = await fetchRouteDependencies(apiUrl, getId(route));
+  const dependencySummary = summarizeRouteDependencies(dependencies);
+  const preview = {
+    route: { id: getId(route), path: route.path, isEnabled: route?.isEnabled !== false },
+    dependencies: dependencySummary,
+  };
+
+  if (!confirm) {
+    return {
+      action: 'delete_route_preview',
+      ...preview,
+      next: 'Call delete_route again with confirm=true and expectedPath set to this route path to delete the route and related handlers/hooks/permissions/guards.',
+    };
+  }
+
+  await deleteRows(apiUrl, 'enfyra_route_handler', dependencies.handlers);
+  await deleteRows(apiUrl, 'enfyra_pre_hook', dependencies.preHooks);
+  await deleteRows(apiUrl, 'enfyra_post_hook', dependencies.postHooks);
+  await deleteRows(apiUrl, 'enfyra_guard', dependencies.guards);
+  await deleteRows(apiUrl, 'enfyra_route_permission', dependencies.permissions);
+  const result = await fetchAPI(apiUrl, `/enfyra_route/${encodeURIComponent(String(getId(route)))}`, { method: 'DELETE' });
+  const routeReload = await reloadRoutes(apiUrl);
+
+  return {
+    action: 'route_deleted',
+    ...preview,
+    deleted: {
+      handlers: dependencies.handlers.map(getId).filter((id) => id !== null && id !== undefined),
+      permissions: dependencies.permissions.map(getId).filter((id) => id !== null && id !== undefined),
+      preHooks: dependencies.preHooks.map(getId).filter((id) => id !== null && id !== undefined),
+      postHooks: dependencies.postHooks.map(getId).filter((id) => id !== null && id !== undefined),
+      guards: dependencies.guards.map(getId).filter((id) => id !== null && id !== undefined),
+      route: getId(route),
+    },
+    result,
+    routeReload,
+  };
+}
+
 async function findHandler(apiUrl, routeId, methodId) {
   const filter = encodeURIComponent(JSON.stringify({
     route: { id: { _eq: routeId } },
@@ -882,6 +991,46 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     })),
   );
 
+  server.tool(
+    'enable_route',
+    'Business operation: enable an existing route. Enabled routes are registered at runtime; disabled routes return 404.',
+    {
+      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.'),
+    },
+    async ({ path, routeId }) => jsonText(await setRouteEnabled(ENFYRA_API_URL, {
+      path,
+      routeId,
+      isEnabled: true,
+    })),
+  );
+
+  server.tool(
+    'disable_route',
+    'Business operation: disable an existing route without deleting metadata. Disabled routes are not registered at runtime and return 404.',
+    {
+      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.'),
+    },
+    async ({ path, routeId }) => jsonText(await setRouteEnabled(ENFYRA_API_URL, {
+      path,
+      routeId,
+      isEnabled: false,
+    })),
+  );
+
+  server.tool(
+    'delete_route',
+    'Business operation: preview-first delete for a route and its route-owned handlers, hooks, guards, and permissions. Use only when a route contract is retired.',
+    {
+      path: z.string().optional().describe('Route path, e.g. /old-endpoint. Use either path or routeId.'),
+      routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
+      expectedPath: z.string().optional().describe('Optional safety check. When confirm=true, pass the path returned by the preview.'),
+      confirm: z.boolean().optional().default(false).describe('false returns a dependency preview only; true deletes the route and related route-owned records.'),
+    },
+    async (input) => jsonText(await deleteRoute(ENFYRA_API_URL, input)),
+  );
+
   server.tool(
     'public_route_methods',
     'Business operation: make existing route methods public/anonymous.',