@enfyra/mcp-server 0.0.89 → 0.0.90

package/README.md

@@ -168,7 +168,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, OAuth, and proxy setup
+- SSR app auth and proxy setup
 - schema, columns, relations, indexes, and validation
 - query filters, sorting, fields, deep relations, and aggregates
 - handlers, hooks, permissions, and RLS
@@ -177,30 +177,6 @@ Use `get_enfyra_examples` from the MCP tool list when asking an LLM to generate
 - files and storage
 - Enfyra admin extensions
 
-## OAuth Setup
-
-OAuth has three different URLs:
-
-| URL | Meaning |
-|-----|---------|
-| Provider callback URL | `{ENFYRA_API_URL}/auth/{provider}/callback` |
-| Enfyra `redirectUri` | Must exactly match the provider callback URL |
-| App `redirect` query | Where Enfyra sends the browser after cookies are set |
-
-Example Google callback when `ENFYRA_API_URL=http://localhost:3000/api`:
-
-```text
-http://localhost:3000/api/auth/google/callback
-```
-
-Start OAuth from the app proxy:
-
-```text
-/enfyra/auth/google?redirect=<absoluteReturnUrl>&cookieBridgePrefix=/enfyra
-```
-
-`appCallbackUrl` is only for manual-token apps that intentionally read token query parameters. SSR apps should prefer proxy-owned cookies.
-
 ## Runtime Safety
 
 The MCP server includes safety guards for LLM callers:

package/package.json

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

package/src/lib/mcp-examples.js

@@ -153,6 +153,96 @@ onUnmounted(() => {
           'Disconnect the singleton socket when the current user/session clears.',
         ],
       },
+      {
+        name: 'Next client provider for authenticated realtime',
+        code: `"use client"
+
+// app/realtime-provider.tsx
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from "react"
+import { io, type Socket } from "socket.io-client"
+
+type RealtimeContextValue = {
+  socket: Socket | null
+  isConnected: boolean
+}
+
+const RealtimeContext = createContext<RealtimeContextValue>({
+  socket: null,
+  isConnected: false
+})
+
+export function RealtimeProvider({
+  user,
+  children
+}: {
+  user: { id: string | number } | null
+  children: React.ReactNode
+}) {
+  const socketRef = useRef<Socket | null>(null)
+  const [isConnected, setConnected] = useState(false)
+
+  useEffect(() => {
+    if (!user) {
+      socketRef.current?.disconnect()
+      socketRef.current = null
+      setConnected(false)
+      return
+    }
+
+    if (socketRef.current) return
+
+    const socket = io("/chat", {
+      path: "/socket.io",
+      withCredentials: true,
+      reconnection: true,
+      reconnectionAttempts: Infinity,
+      reconnectionDelay: 2000,
+      reconnectionDelayMax: 30000
+    })
+
+    socket.on("connect", () => setConnected(true))
+    socket.on("disconnect", () => setConnected(false))
+    socketRef.current = socket
+
+    return () => {
+      socket.off("connect")
+      socket.off("disconnect")
+      socket.disconnect()
+      socketRef.current = null
+      setConnected(false)
+    }
+  }, [user])
+
+  const value = useMemo(
+    () => ({ socket: socketRef.current, isConnected }),
+    [isConnected]
+  )
+
+  return <RealtimeContext.Provider value={value}>{children}</RealtimeContext.Provider>
+}
+
+export function useRealtime() {
+  return useContext(RealtimeContext)
+}
+
+// app/chat/page.tsx
+// const { socket } = useRealtime()
+// useEffect(() => {
+//   if (!socket) return
+//   const onMessage = event => {
+//     // Update local UI state, then debounce REST refresh if full state is needed.
+//   }
+//   socket.on("chat:message", onMessage)
+//   return () => socket.off("chat:message", onMessage)
+// }, [socket])`,
+        notes: [
+          'Create the Socket.IO client once in a top-level client provider after the current user is known.',
+          'Use the websocket namespace path from live metadata, such as /chat, and keep the transport path as /socket.io.',
+          'Proxy /socket.io through Next rewrites to the Enfyra app bridge /ws/socket.io so cookies remain same-origin.',
+          'Pages/components should only subscribe/unsubscribe listeners; they should not create independent socket connections.',
+          'Disconnect the singleton socket when the current user/session clears.',
+        ],
+      },
       {
         name: 'OAuth provider setup values',
         code: `// Enfyra OAuth config row, stored in enfyra_oauth_config.

package/src/lib/mcp-instructions.js

@@ -156,7 +156,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- You may **mutate** `@DATA` / `$ctx.$data` in place, or **return** a value: a non-`undefined` return replaces `$ctx.$data` as the response body.',
     '',
     '### Dynamic script syntax preference',
-    '- When writing server-side Enfyra scripts, prefer template macros over raw `$ctx` access: use `@BODY`, `@QUERY`, `@PARAMS`, `@USER`, `@REPOS`, `@HELPERS`, `@STORAGE`, `@SOCKET`, `@TRIGGER`, `@DATA`, `@ERROR`, `@ENV`, and `@THROW400`–`@THROW503`.',
+    '- When writing server-side Enfyra scripts, prefer template macros over raw `$ctx` access: use `@BODY`, `@QUERY`, `@PARAMS`, `@USER`, `@REQ`, `@RES`, `@REPOS`, `@HELPERS`, `@FETCH`, `@STORAGE`, `@UPLOADED_FILE`, `@CACHE`, `@SOCKET`, `@TRIGGER`, `@DATA`, `@ERROR`, `@STATUS`, `@ENV`, `@PKGS`, `@LOGS`, `@SHARE`, `@API`, and `@THROW` / `@THROW400`–`@THROW503` when those context fields are available.',
     '- Use Enfyra native throw helpers for intentional errors: `@THROW400("message")`, `@THROW403()`, `@THROW404("resource", id)`, or `$ctx.$throw[400]("message")`. Do not generate `throw new Error(...)` for user/domain errors in handlers, hooks, flows, websocket events, OAuth scripts, or admin-generated scripts.',
     '- For regular app data that must be encrypted at rest, create the column with `isEncrypted=true`; Enfyra database-query hooks will encrypt on insert/update and decrypt after select. `isEncrypted` does not imply immutability; use `isUpdatable=false` separately only when the field itself must be immutable. Do not filter or sort on encrypted fields. Do not generate new route pre-hooks for manual encryption.',
     '- Enfyra scripts use `$helpers.$crypto` for bounded crypto helpers such as `randomUUID()`, `randomBytes(size, encoding)`, `sha256(value, encoding)`, `hmacSha256(value, secret, encoding)`, and `generateSshKeyPair(comment)`. Do not generate legacy `$helpers.$ssh` or `$helpers.$secrets` usage.',
@@ -288,8 +288,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '-   `@SOCKET.broadcastToRoom(room, event, data)` — send to a named room in the current websocket gateway/namespace except the triggering socket (WS context only).',
     '-   `@SOCKET.emitToGateway(path, event, data)` — broadcast to all connections on a gateway/namespace.',
     '-   `@SOCKET.broadcast(event, data)` — broadcast to all connections on all gateways.',
+    '-   `await @SOCKET.roomSize(room)` — count connected sockets in a room across registered gateways; available in server script socket context.',
     '-   `@SOCKET.disconnect()` — force-disconnect the current socket from the gateway (WS context only). Use in connection handler to reject, or in event handler to kick user.',
-    '-   In **HTTP** handler/hook context: `reply`, `join`, `leave`, `disconnect`, `emitToCurrentRoom`, and `broadcastToRoom` are not available (no bound socket). Use `emitToUser`, `emitToRoom(path, room, event, data)`, `emitToGateway`, and `broadcast`.',
+    '-   In **HTTP** handler/hook context: `reply`, `join`, `leave`, `disconnect`, `emitToCurrentRoom`, and `broadcastToRoom` are not available (no bound socket). Use `emitToUser`, `emitToRoom(path, room, event, data)`, `emitToGateway`, `broadcast`, and `roomSize`.',
     '- **Context**: Connection — `@BODY` = {id, ip, headers}, `@USER` if auth. Event — `@BODY` = payload, `@USER` if auth. Both have `@SOCKET`.',
     '- **ACK + results (recommended UX):** client can emit an event with Socket.IO ack callback. Server immediately acks `{ queued: true, requestId, eventName }` (or `{ queued: false, error }`). The handler result is returned asynchronously via `ws:result` or `ws:error` with the same `requestId`.',
     '- **Client**: Browser apps must connect through the app/Nuxt Socket.IO bridge, not the hidden Enfyra backend. The backend gateway metadata path is the namespace, e.g. `/chat`. A third app should connect with `io("/chat", { path: "/socket.io", withCredentials: true })` and proxy `/socket.io/**` to the Enfyra app bridge `/ws/socket.io/**`. Direct Enfyra app clients may connect with `io("/ws/chat", { path: "/ws/socket.io", withCredentials: true })` when using the built-in bridge convention.',

package/src/mcp-server-entry.mjs

@@ -866,25 +866,44 @@ server.tool(
     const payload = {
       transformer: {
         rule: 'Dynamic server scripts are transformed before sandbox execution. Macros expand to $ctx paths; comments are not transformed.',
-        preferredSyntax: 'Prefer template macros in generated Enfyra scripts. Use @BODY/@QUERY/@PARAMS/@USER/@REPOS/@CACHE/@HELPERS/@STORAGE/@SOCKET/@TRIGGER/@DATA/@ERROR/@ENV/@THROW* instead of raw $ctx access whenever a macro exists. Use raw $ctx only for fields without a macro.',
+        preferredSyntax: 'Prefer template macros in generated Enfyra scripts. Use macros such as @BODY/@QUERY/@PARAMS/@USER/@REQ/@RES/@REPOS/@CACHE/@HELPERS/@FETCH/@STORAGE/@UPLOADED_FILE/@SOCKET/@TRIGGER/@DATA/@ERROR/@STATUS/@ENV/@PKGS/@LOGS/@SHARE/@API/@THROW* instead of raw $ctx access whenever a macro exists. Use raw $ctx only for fields without a macro.',
         coreMacros: {
-          '@BODY': '$ctx.$body',
-          '@QUERY': '$ctx.$query',
-          '@PARAMS': '$ctx.$params',
-          '@USER': '$ctx.$user',
-          '@ENV': '$ctx.$env',
-          '@REPOS': '$ctx.$repos',
           '@CACHE': '$ctx.$cache',
+          '@REPOS': '$ctx.$repos',
           '@HELPERS': '$ctx.$helpers',
           '@STORAGE': '$ctx.$storage',
-          '@SOCKET': '$ctx.$socket',
+          '@FETCH': '$ctx.$helpers.$fetch',
+          '@LOGS': '$ctx.$logs',
+          '@BODY': '$ctx.$body',
+          '@ENV': '$ctx.$env',
           '@DATA': '$ctx.$data',
+          '@PARAMS': '$ctx.$params',
+          '@QUERY': '$ctx.$query',
+          '@USER': '$ctx.$user',
+          '@REQ': '$ctx.$req',
+          '@RES': '$ctx.$res',
+          '@SHARE': '$ctx.$share',
+          '@API': '$ctx.$api',
+          '@UPLOADED_FILE': '$ctx.$uploadedFile',
+          '@PKGS': '$ctx.$pkgs',
+          '@SOCKET': '$ctx.$socket',
+          '@TRIGGER': '$ctx.$trigger',
+          '@FLOW': '$ctx.$flow',
+          '@FLOW_PAYLOAD': '$ctx.$flow.$payload',
+          '@FLOW_LAST': '$ctx.$flow.$last',
+          '@FLOW_META': '$ctx.$flow.$meta',
+          '@THROW400': "$ctx.$throw['400']",
+          '@THROW401': "$ctx.$throw['401']",
+          '@THROW403': "$ctx.$throw['403']",
+          '@THROW404': "$ctx.$throw['404']",
+          '@THROW409': "$ctx.$throw['409']",
+          '@THROW422': "$ctx.$throw['422']",
+          '@THROW429': "$ctx.$throw['429']",
+          '@THROW500': "$ctx.$throw['500']",
+          '@THROW503': "$ctx.$throw['503']",
+          '@THROW': '$ctx.$throw',
           '@STATUS': '$ctx.$statusCode',
           '@ERROR': '$ctx.$error',
-          '@PKGS': '$ctx.$pkgs',
-          '@LOGS': '$ctx.$logs',
-          '@SHARE': '$ctx.$share',
-          '@TRIGGER(name,payload)': '$ctx.$trigger(name,payload)',
         },
         flowMacros: {
           '@FLOW': '$ctx.$flow',
@@ -900,6 +919,8 @@ server.tool(
         },
         throws: '@THROW400 through @THROW503 and @THROW map to $ctx.$throw helpers.',
         helpers: {
+          core: '$ctx.$helpers includes $bcrypt.hash/compare, autoSlug(text), $fetch, $sleep(ms) capped by the runtime, and $crypto. HTTP and GraphQL contexts also expose $jwt through $ctx.$helpers.',
+          fetch: '@FETCH maps to $ctx.$helpers.$fetch for outbound HTTP calls from server scripts. Keep secrets in encrypted fields instead of embedding them in sourceCode.',
           crypto: '$ctx.$helpers.$crypto exposes bounded runtime crypto helpers: randomUUID(), randomBytes(size, encoding), sha256(value, encoding), hmacSha256(value, secret, encoding), and generateSshKeyPair(comment). Use generateSshKeyPair for SSH key material. Do not use legacy $ctx.$helpers.$ssh.',
           files: '$ctx.$storage.$upload and $ctx.$storage.$update accept file: @UPLOADED_FILE for request uploads and stream from the server temp file path. $ctx.$storage.$registerFile creates a enfyra_file record for an object that already exists in storage without uploading bytes. Use buffer only for small generated/transformed files; do not use @UPLOADED_FILE.buffer.',
         },
@@ -908,7 +929,7 @@ server.tool(
       contexts: {
         preHook: {
           runs: 'Before handler.',
-          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REPOS', '@CACHE', '@HELPERS', '@STORAGE', '@THROW*', '@SOCKET emit helpers'],
+          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REQ', '@REPOS', '@CACHE', '@HELPERS', '@FETCH', '@STORAGE', '@THROW*', '@SOCKET global emit helpers/roomSize'],
           queryContract: '@QUERY.filter is initialized as an object. When adding RLS/scope filters in pre-hooks, merge directly with _and; do not add defensive type checks around @QUERY.filter.',
           projectionContract: 'For canonical table reads, preserve client-controlled query shape. Do not override @QUERY.fields, @QUERY.deep, @QUERY.sort, @QUERY.limit, @QUERY.page, @QUERY.meta, @QUERY.aggregate, or debugMode. RLS should only merge security constraints into @QUERY.filter.',
           rlsPattern: 'For relation-scoped reads, mutate @QUERY.filter instead of returning data. Example: const incomingFilter = @QUERY.filter; const scope = { memberships: { member: { id: { _eq: @USER.id } } } }; @QUERY.filter = Object.keys(incomingFilter).length ? { _and: [incomingFilter, scope] } : scope;',
@@ -916,28 +937,28 @@ server.tool(
         },
         handler: {
           runs: 'Main route logic, or canonical CRUD if no handler overrides.',
-          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@UPLOADED_FILE for multipart request file metadata', '@REPOS.main', '@REPOS.<table>', '@CACHE', '@HELPERS', '@STORAGE', '@PKGS', '@SOCKET emit helpers', '@TRIGGER'],
+          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REQ', '@RES when response streaming is available', '@UPLOADED_FILE for multipart request file metadata', '@REPOS.main', '@REPOS.<table>', '@CACHE', '@HELPERS', '@FETCH', '@STORAGE', '@PKGS', '@SOCKET global emit helpers/roomSize', '@TRIGGER'],
           queryContract: 'When a handler wraps a canonical table read, pass through client fields/deep/sort/page/limit/meta/aggregate/debugMode unless the route is a clearly custom summary or workflow endpoint.',
           returnBehavior: 'Return value becomes response body unless post-hook changes it.',
         },
         postHook: {
           runs: 'After handler, including error path.',
-          data: ['@DATA', '@STATUS', '@ERROR', '@BODY', '@QUERY', '@USER', '@CACHE', '@SHARE', '@API'],
+          data: ['@DATA', '@STATUS', '@ERROR', '@BODY', '@QUERY', '@PARAMS', '@USER', '@REQ', '@CACHE', '@HELPERS', '@FETCH', '@STORAGE', '@SHARE', '@API'],
           returnBehavior: 'Mutate @DATA/$ctx.$data or return a non-undefined replacement response.',
         },
         flowStep: {
           runs: 'Inside flow execution or admin flow step test.',
-          data: ['@FLOW_PAYLOAD', '@FLOW_LAST', '@FLOW', '@FLOW_META', '#table_name', '@CACHE', '@HELPERS', '@STORAGE', '@SOCKET', '@TRIGGER'],
+          data: ['@BODY payload', '@USER if provided', '@FLOW_PAYLOAD', '@FLOW_LAST', '@FLOW', '@FLOW_META', '#table_name', '@CACHE', '@HELPERS', '@FETCH', '@STORAGE', '@SOCKET global emit helpers/roomSize', '@TRIGGER'],
           resultBehavior: 'Step return value is injected into @FLOW.<step.key> and @FLOW_LAST.',
           branching: 'Condition steps use JavaScript truthy/falsy result; child branch is true/false.',
         },
         websocketConnection: {
           runs: 'Socket.IO connection handler.',
-          data: ['@BODY connection info', '@USER if authenticated', '@SOCKET reply/join/leave/disconnect/emit helpers'],
+          data: ['@BODY connection info', '@DATA connection info', '@REQ websocket request metadata', '@API request metadata', '@USER if authenticated', '@HELPERS', '@FETCH', '@SOCKET reply/join/leave/disconnect/emit helpers/roomSize'],
         },
         websocketEvent: {
           runs: 'Socket.IO event handler.',
-          data: ['@BODY event payload', '@USER if authenticated', '@SOCKET reply/join/leave/disconnect/emit helpers'],
+          data: ['@BODY event payload', '@DATA event payload', '@REQ websocket request metadata', '@API request metadata', '@USER if authenticated', '@HELPERS', '@FETCH', '@SOCKET reply/join/leave/disconnect/emit helpers/roomSize'],
           resultBehavior: 'Client ack receives queued state first; handler result is emitted asynchronously as ws:result/ws:error with requestId.',
         },
         graphqlResolver: {
@@ -959,7 +980,7 @@ server.tool(
           wrongSingleRecordAccess: 'Do not use result.data.id, do not return result.data when one object is expected, and do not assume create/update returns the bare row object.',
           countPattern: 'To count records in custom code, do not fetch full rows. Use const result = await @REPOS.main.find({ fields: "id", limit: 1, meta: filter ? "filterCount" : "totalCount", ...(filter ? { filter } : {}) }); then read result.meta.filterCount or result.meta.totalCount.',
         },
-        socketInHttpOrFlow: 'HTTP/flow context can emitToUser/emitToRoom/emitToGateway/broadcast, but cannot reply/join/leave/disconnect/emitToCurrentRoom/broadcastToRoom because there is no bound socket. emitToRoom requires an explicit gateway path: emitToRoom(path, room, event, data).',
+        socketInHttpOrFlow: 'HTTP/flow context can emitToUser/emitToRoom/emitToGateway/broadcast and roomSize, but cannot reply/join/leave/disconnect/emitToCurrentRoom/broadcastToRoom because there is no bound socket. emitToRoom requires an explicit gateway path: emitToRoom(path, room, event, data). roomSize(room) counts sockets in that room across registered gateways.',
         packages: 'Server packages installed through install_package are exposed as $ctx.$pkgs.packageName in server scripts.',
         files: 'Upload helpers are on $storage; raw create_record on enfyra_file is not equivalent to multipart upload/storage rollback. For multipart request files, pass file: @UPLOADED_FILE to @STORAGE.$upload/@STORAGE.$update so Enfyra streams from disk-backed temp storage. Use @STORAGE.$registerFile only when the object already exists in storage and the script should create the enfyra_file record without uploading bytes. Use buffer only for small generated files.',
       },