@enfyra/mcp-server 0.0.103 → 0.0.105

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
@@ -186,7 +187,7 @@ The MCP server includes safety guards for LLM callers:
 - `validate_dynamic_script` checks handler, hook, flow, websocket, GraphQL, and bootstrap script source without saving.
 - `validate_extension_code` checks Enfyra admin extension code through `/enfyra_extension/preview` without saving.
 - `compiledCode` is generated from `sourceCode` and may differ textually because macros are expanded; the MCP server never accepts hand-written `compiledCode`.
-- JSON responses include `compressionStats` with estimated token savings for the columnar response format.
+- JSON responses include `compressionStats` with estimated token savings. Arrays of objects are converted to columnar form only when the compact shape is smaller than raw JSON.
 - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.103",
+  "version": "0.0.105",
   "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

@@ -35,7 +35,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Validate behavior with `test_rest_endpoint`, `run_admin_test`, `test_flow_step`, or the route-specific tool before claiming a dynamic feature works.',
     '',
     '### Core Contracts',
-    '- Tool JSON responses use `responseFormat: "json+columnar-v1"`. Any array of objects is encoded as `{ format: "columnar-v1", columns: [...], rows: [[...]], rowCount }`; read each row value by matching `columns[index]` to `rows[n][index]`. Do not guess object keys inside `rows`. `compressionStats` estimates token savings from the compact response; use it only when the user asks about savings.',
+    '- Tool JSON responses use `responseFormat: "json+columnar-v1"`. Large arrays of objects may be encoded as `{ format: "columnar-v1", columns: [...], rows: [[...]], rowCount }` only when that is smaller than raw JSON; read each row value by matching `columns[index]` to `rows[n][index]`. Do not guess object keys inside `rows`. `compressionStats` estimates token savings and includes whether compression was applied; use it only when the user asks about savings.',
     '- `query_table` and `get_all_routes` require explicit intent: pass `limit` for bounded reads or `all: true` for a complete list. Do not invent arbitrary limits such as 30 or 50.',
     '- Read tools are minimal by default. Pass explicit `fields`; use metadata inspection before guessing field/relation names. Field exclusion mode exists: `fields=-compiledCode`, and `fields=id,-compiledCode` still means all readable fields except `compiledCode`.',
     '- Mutations return ids/status by default. Re-read with `find_one_record` or `query_table` and explicit `fields` when the saved row matters.',
@@ -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',

package/src/lib/response-format.js

@@ -66,60 +66,73 @@ function estimateTokens(jsonText) {
   return Math.ceil(jsonText.length / 4);
 }
 
-function buildCompressionStats(originalPayload, compactPayload) {
+function buildCompressionStats(originalPayload, candidatePayload, selectedPayload, applied) {
   const originalTokens = estimateTokens(safeJsonStringify(originalPayload));
-  const compactTokens = estimateTokens(safeJsonStringify(compactPayload));
-  const savedTokens = originalTokens - compactTokens;
+  const candidateTokens = estimateTokens(safeJsonStringify(candidatePayload));
+  const responseTokens = estimateTokens(safeJsonStringify(selectedPayload));
+  const candidateSavedTokens = originalTokens - candidateTokens;
+  const candidateSavedPercent = originalTokens > 0
+    ? Number(((candidateSavedTokens / originalTokens) * 100).toFixed(2))
+    : 0;
+  const savedTokens = originalTokens - responseTokens;
   const savedPercent = originalTokens > 0
     ? Number(((savedTokens / originalTokens) * 100).toFixed(2))
     : 0;
   return {
     originalTokens,
-    compactTokens,
+    compactTokens: responseTokens,
     savedTokens,
     savedPercent,
+    applied,
+    candidateCompactTokens: candidateTokens,
+    candidateSavedTokens,
+    candidateSavedPercent,
   };
 }
 
-function attachCompressionStats(originalPayload, formattedPayload) {
+function attachCompressionStats(originalPayload, candidatePayload, selectedPayload, applied) {
   if (
-    isPlainObject(formattedPayload)
-    && formattedPayload.responseFormat === RESPONSE_FORMAT
-    && formattedPayload[COMPRESSION_STATS_FIELD]
+    isPlainObject(selectedPayload)
+    && selectedPayload.responseFormat === RESPONSE_FORMAT
+    && selectedPayload[COMPRESSION_STATS_FIELD]
   ) {
-    return formattedPayload;
+    return selectedPayload;
   }
-  if (!isPlainObject(formattedPayload)) {
-    const compactPayload = {
-      responseFormat: RESPONSE_FORMAT,
-      value: formattedPayload,
-    };
+  return {
+    ...selectedPayload,
+    [COMPRESSION_STATS_FIELD]: buildCompressionStats(originalPayload, candidatePayload, selectedPayload, applied),
+  };
+}
+
+function wrapPayload(payload) {
+  if (!isPlainObject(payload)) {
     return {
-      ...compactPayload,
-      [COMPRESSION_STATS_FIELD]: buildCompressionStats(originalPayload, compactPayload),
+      responseFormat: RESPONSE_FORMAT,
+      value: payload,
     };
   }
   return {
-    ...formattedPayload,
-    [COMPRESSION_STATS_FIELD]: buildCompressionStats(originalPayload, formattedPayload),
+    responseFormat: RESPONSE_FORMAT,
+    ...payload,
   };
 }
 
 export function formatJsonPayload(payload) {
-  const formatted = toColumnar(payload);
-  if (!isPlainObject(formatted)) {
-    return attachCompressionStats(payload, {
-      responseFormat: RESPONSE_FORMAT,
-      value: formatted,
-    });
-  }
-  if (formatted.responseFormat === RESPONSE_FORMAT) {
-    return attachCompressionStats(payload, formatted);
+  if (
+    isPlainObject(payload)
+    && payload.responseFormat === RESPONSE_FORMAT
+    && payload[COMPRESSION_STATS_FIELD]
+  ) {
+    return payload;
   }
-  return attachCompressionStats(payload, {
-    responseFormat: RESPONSE_FORMAT,
-    ...formatted,
-  });
+
+  const originalPayload = wrapPayload(payload);
+  const columnarPayload = wrapPayload(toColumnar(payload));
+  const originalTokens = estimateTokens(safeJsonStringify(originalPayload));
+  const candidateTokens = estimateTokens(safeJsonStringify(columnarPayload));
+  const shouldApplyColumnar = candidateTokens < originalTokens;
+  const selectedPayload = shouldApplyColumnar ? columnarPayload : originalPayload;
+  return attachCompressionStats(originalPayload, columnarPayload, selectedPayload, shouldApplyColumnar);
 }
 
 export function jsonContent(payload, { pretty = false } = {}) {