@enfyra/mcp-server 0.0.101 → 0.0.102

package/README.md

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

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`.',
+    '- 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.',
     '- `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.',

package/src/lib/response-format.js

@@ -1,5 +1,6 @@
 const RESPONSE_FORMAT = 'json+columnar-v1';
 const COLUMNAR_FORMAT = 'columnar-v1';
+const COMPRESSION_STATS_FIELD = 'compressionStats';
 
 function isPlainObject(value) {
   if (!value || typeof value !== 'object') return false;
@@ -50,19 +51,75 @@ function toColumnar(value, seen = new WeakSet()) {
   return output;
 }
 
+function safeJsonStringify(value) {
+  const seen = new WeakSet();
+  return JSON.stringify(value, (_key, entry) => {
+    if (!entry || typeof entry !== 'object') return entry;
+    if (seen.has(entry)) return '[Circular]';
+    seen.add(entry);
+    return entry;
+  });
+}
+
+function estimateTokens(jsonText) {
+  if (!jsonText) return 0;
+  return Math.ceil(jsonText.length / 4);
+}
+
+function buildCompressionStats(originalPayload, compactPayload) {
+  const originalTokens = estimateTokens(safeJsonStringify(originalPayload));
+  const compactTokens = estimateTokens(safeJsonStringify(compactPayload));
+  const savedTokens = originalTokens - compactTokens;
+  const savedPercent = originalTokens > 0
+    ? Number(((savedTokens / originalTokens) * 100).toFixed(2))
+    : 0;
+  return {
+    originalTokens,
+    compactTokens,
+    savedTokens,
+    savedPercent,
+  };
+}
+
+function attachCompressionStats(originalPayload, formattedPayload) {
+  if (
+    isPlainObject(formattedPayload)
+    && formattedPayload.responseFormat === RESPONSE_FORMAT
+    && formattedPayload[COMPRESSION_STATS_FIELD]
+  ) {
+    return formattedPayload;
+  }
+  if (!isPlainObject(formattedPayload)) {
+    const compactPayload = {
+      responseFormat: RESPONSE_FORMAT,
+      value: formattedPayload,
+    };
+    return {
+      ...compactPayload,
+      [COMPRESSION_STATS_FIELD]: buildCompressionStats(originalPayload, compactPayload),
+    };
+  }
+  return {
+    ...formattedPayload,
+    [COMPRESSION_STATS_FIELD]: buildCompressionStats(originalPayload, formattedPayload),
+  };
+}
+
 export function formatJsonPayload(payload) {
   const formatted = toColumnar(payload);
   if (!isPlainObject(formatted)) {
-    return {
+    return attachCompressionStats(payload, {
       responseFormat: RESPONSE_FORMAT,
       value: formatted,
-    };
+    });
   }
-  if (formatted.responseFormat === RESPONSE_FORMAT) return formatted;
-  return {
+  if (formatted.responseFormat === RESPONSE_FORMAT) {
+    return attachCompressionStats(payload, formatted);
+  }
+  return attachCompressionStats(payload, {
     responseFormat: RESPONSE_FORMAT,
     ...formatted,
-  };
+  });
 }
 
 export function jsonContent(payload, { pretty = false } = {}) {