@enfyra/mcp-server 0.0.88 → 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:
@@ -216,7 +192,7 @@ The MCP server includes safety guards for LLM callers:
 
 ## Query Notes
 
-Use explicit `fields` in read tools. Include mode is the default, such as `fields=id,email`. Any excluded field switches that scope to exclude mode: `fields=-compiledCode` returns all readable fields except `compiledCode`, and `fields=id,-compiledCode` still means all except `compiledCode`. Dotted exclusions such as `fields=-owner.avatar` work for relation fields when the relation exists in metadata.
+Use explicit `fields` in read tools. Include mode is the default, such as `fields=id,email`. Any excluded field switches that scope to exclude mode: `fields=-compiledCode` returns all readable fields except `compiledCode`, and `fields=id,-compiledCode` still means all except `compiledCode`. Dotted exclusions such as `fields=-owner.avatar` work for relation fields when the relation exists in metadata. Every list/query call must pass either `limit` for a bounded page or `all: true` for a complete list. When a caller needs every matching row, pass `all: true` to `query_table` or `get_all_routes`; the tool sends REST `limit=0` instead of making the model choose an arbitrary page size like 30 or 50.
 
 ## Enfyra URL Pattern
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.88",
+  "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.
@@ -375,15 +465,20 @@ create_column({
           'Always pass fields when you need more than ids; query_table without fields intentionally returns only the primary key.',
           'Use inspect_table first when you do not know valid column names or relation propertyName values.',
           'Use count_records when only the count is needed.',
+          'When the user asks for all matching rows, pass all: true instead of choosing an arbitrary page size such as 30 or 50.',
         ],
       },
       {
         name: 'List current user conversations through RLS',
-        code: `GET /enfyra/chat_conversation?fields=id,kind,title,lastMessage.id,lastMessage.text,lastMessage.createdAt&limit=0`,
+        code: `query_table({
+  tableName: "chat_conversation",
+  fields: ["id", "kind", "title", "lastMessage.id", "lastMessage.text", "lastMessage.createdAt"],
+  all: true
+})`,
         notes: [
           'Use a conversation read pre-hook/RLS boundary so the route only returns conversations visible to @USER.',
           'lastMessage is a relation to chat_message; do not duplicate preview fields on chat_conversation.',
-          'limit=0 means load all matching conversation rows.',
+          'all: true tells MCP to send REST limit=0 and load all matching conversation rows.',
           'Do not fetch messages for every conversation on initial list load; load messages after selecting a conversation.',
         ],
       },

package/src/lib/mcp-instructions.js

@@ -38,7 +38,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- If generating concrete code, schema payloads, SSR app config, OAuth wiring, Socket.IO clients/events, flows, files, extensions, or permission/RLS examples, call **`get_enfyra_examples`** for the matching category before writing the final answer. Examples are grouped by category and are intentionally more concrete than these global rules.',
     '- Treat hardcoded instructions as operating rules, but use live discovery as the final check for this running instance. Do not infer missing capabilities from a narrow tool schema; check metadata/routes or the relevant specialized tool first.',
     '- If there is no dedicated MCP tool for a subsystem, use the route-backed metadata table with `query_table` / `create_record` / `update_record` / `delete_record`, after confirming that table has a route. If the table is no-route, use the canonical specialized tool or parent table workflow instead.',
-    '- MCP read tools are intentionally **minimal by default**. `query_table` without `fields` returns only the table primary key with a small hint. Always pass explicit `fields` when you need details, and use `inspect_table` / `inspect_route` before guessing field names.',
+    '- MCP read tools are intentionally **minimal by default**. `query_table` without `fields` returns only the table primary key with a small hint. Always pass explicit `fields` when you need details, and use `inspect_table` / `inspect_route` before guessing field names. Every list/query call must explicitly pass either `limit` for a bounded page or `all: true` for a complete list. When the user asks for all matching rows, pass `all: true` instead of inventing arbitrary limits such as 30 or 50.',
     '- MCP mutation tools return only ids/status by default. If you need the saved row, immediately call `find_one_record` or `query_table` with explicit `fields`; do not expect create/update tools to echo full records.',
     '- **Operator posture:** act from the Enfyra contracts encoded here and in live metadata. Do not turn normal implementation details into speculative warnings. Ask the user only when a new design/product decision is needed, when metadata is genuinely ambiguous, or when a tool/runtime result proves a concrete problem. If a behavior is expected by contract, state it as expected behavior or omit it; do not present it as an audit finding.',
     '',
@@ -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.',
       },
@@ -1012,17 +1033,24 @@ server.tool(
   },
 );
 
-server.tool('query_table', 'Query any route-backed table. Default response is minimal; pass fields explicitly for detail.', {
+server.tool('query_table', 'Query any route-backed table. Response is minimal unless fields is explicit. Every call must pass either limit or all=true.', {
   tableName: z.string().describe('Table name to query'),
   filter: z.string().optional().describe('Filter object as JSON string. Examples: \'{"status": {"_eq": "active"}}\''),
   sort: z.string().optional().describe('Sort field. Prefix with - for descending (e.g., "createdAt", "-id")'),
   page: z.number().optional().describe('Page number (default: 1)'),
-  limit: z.number().optional().describe('Items per page. Default: 10. Use count_records for counts.'),
+  limit: z.number().int().min(0).optional().describe('Items per page. Required unless all=true. Do not invent arbitrary limits for "all"; use all=true instead. Use count_records for counts.'),
+  all: z.boolean().optional().default(false).describe('Return all matching rows by sending REST limit=0. Use this when the user asks for all rows or a complete list.'),
   fields: z.array(z.string()).optional().describe('Fields to select. If omitted, MCP selects only the table primary key to avoid oversized responses.'),
   meta: z.string().optional().describe('Optional REST meta request, e.g. "totalCount", "filterCount", or aggregate modes supported by the route. Use count_records for simple counts.'),
   deep: z.string().optional().describe('Optional deep relation fetch object as JSON string. Keys must be relation propertyName values.'),
   aggregate: z.string().optional().describe('Optional aggregate object as JSON string, keyed by real fields/relations. Results are returned in response.meta.aggregate when supported.'),
-}, async ({ tableName, filter, sort, page, limit, fields, meta, deep, aggregate }) => {
+}, async ({ tableName, filter, sort, page, limit, all, fields, meta, deep, aggregate }) => {
+  if (!all && limit === undefined) {
+    throw new Error('query_table requires either limit or all=true. Do not rely on implicit default page sizes.');
+  }
+  if (all && limit !== undefined) {
+    throw new Error('query_table accepts either all=true or limit, not both.');
+  }
   validateTableName(tableName);
   validateFilter(filter);
   parseJsonArg(deep, undefined);
@@ -1036,7 +1064,8 @@ server.tool('query_table', 'Query any route-backed table. Default response is mi
   if (meta) queryParams.set('meta', meta);
   if (deep) queryParams.set('deep', deep);
   if (aggregate) queryParams.set('aggregate', aggregate);
-  queryParams.set('limit', String(limit || 10));
+  const effectiveLimit = all ? 0 : limit;
+  queryParams.set('limit', String(effectiveLimit));
   queryParams.set('fields', selectedFields.join(','));
 
   const query = queryParams.toString();
@@ -1046,7 +1075,8 @@ server.tool('query_table', 'Query any route-backed table. Default response is mi
     success: result?.success,
     tableName,
     fields: selectedFields,
-    limit: limit || 10,
+    limit: effectiveLimit,
+    all: !!all,
     queryOptions: {
       meta: meta || null,
       deep: deep ? parseJsonArg(deep, null) : null,
@@ -2014,11 +2044,18 @@ server.tool(
   },
 );
 
-server.tool('get_all_routes', 'List route definitions with minimal fields. Call inspect_route for handlers/hooks/permissions detail.', {
+server.tool('get_all_routes', 'List route definitions with minimal fields. Every call must pass either limit or all=true. Call inspect_route for handlers/hooks/permissions detail.', {
   includeDisabled: z.boolean().optional().default(false).describe('Include disabled routes'),
   search: z.string().optional().describe('Optional path or table substring filter. Use this before creating a route to check duplicates.'),
-  limit: z.number().optional().describe('Maximum routes returned after search. Default 50 to keep response small.'),
-}, async ({ includeDisabled, search, limit }) => {
+  limit: z.number().int().positive().optional().describe('Maximum routes returned after search. Required unless all=true. Do not invent arbitrary limits for "all"; use all=true instead.'),
+  all: z.boolean().optional().default(false).describe('Return all matched routes. Use this when the user asks for all routes or a complete route list.'),
+}, async ({ includeDisabled, search, limit, all }) => {
+  if (!all && limit === undefined) {
+    throw new Error('get_all_routes requires either limit or all=true. Do not rely on implicit default page sizes.');
+  }
+  if (all && limit !== undefined) {
+    throw new Error('get_all_routes accepts either all=true or limit, not both.');
+  }
   const filter = includeDisabled ? {} : { isEnabled: { _eq: true } };
   const queryParams = new URLSearchParams({
     filter: JSON.stringify(filter),
@@ -2026,7 +2063,6 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Call
     limit: '1000',
   });
   const result = await fetchAPI(ENFYRA_API_URL, `/enfyra_route?${queryParams.toString()}`);
-  const routeLimit = limit || 50;
   const q = search ? search.toLowerCase() : null;
   const allRoutes = summarizeRoutes(result);
   const matchedRoutes = q
@@ -2035,12 +2071,14 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Call
         mainTable: route.mainTable,
       }).toLowerCase().includes(q))
     : allRoutes;
+  const routeLimit = all ? matchedRoutes.length : limit;
   const payload = {
     statusCode: result?.statusCode,
     success: result?.success,
     totalRouteCount: allRoutes.length,
     matchedRouteCount: matchedRoutes.length,
     returnedRouteCount: Math.min(matchedRoutes.length, routeLimit),
+    all: !!all,
     search: search || null,
     routes: matchedRoutes.slice(0, routeLimit),
     detailHint: matchedRoutes.length > routeLimit