@enfyra/mcp-server 0.0.88 → 0.0.89

package/README.md

@@ -216,7 +216,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.89",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -375,15 +375,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.',
     '',

package/src/mcp-server-entry.mjs

@@ -1012,17 +1012,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 +1043,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 +1054,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 +2023,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 +2042,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 +2050,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