@enfyra/mcp-server 0.0.101 → 0.0.103

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.103",
   "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/platform-operation-tools.js

@@ -493,9 +493,10 @@ async function resolveApiEndpointWorkflowState(apiUrl, opts) {
   const routeId = getId(route);
   const availableMethods = methodNamesFromRecords(route?.availableMethods || [], methodIdNameMap);
   const publicMethods = methodNamesFromRecords(route?.publicMethods || [], methodIdNameMap);
+  const methodAvailable = availableMethods.includes(methodName);
   const routeNeedsUpdate = !!route && (
     route.isEnabled === false
-    || !availableMethods.includes(methodName)
+    || !methodAvailable
     || (access === 'public' && !publicMethods.includes(methodName))
     || (access === 'private' && publicMethods.includes(methodName))
     || (opts.description !== undefined && route.description !== opts.description)
@@ -549,8 +550,8 @@ async function resolveApiEndpointWorkflowState(apiUrl, opts) {
         handlerId: getId(handler),
         reason: handlerNeedsOverwrite && !opts.overwrite ? 'Existing handler differs. Re-run with overwrite=true to update it.' : undefined,
       })
-      : step(route ? 'pending' : 'waiting', 'save_handler', 'Create route handler', {
-        reason: route ? undefined : 'Route must exist first.',
+      : step(route && methodAvailable ? 'pending' : 'waiting', 'save_handler', 'Create route handler', {
+        reason: !route ? 'Route must exist first.' : methodAvailable ? undefined : 'Route method must be available first.',
       }),
   ];
 
@@ -725,25 +726,40 @@ async function applyApiEndpointWorkflowStep(apiUrl, state, opts, stepId) {
 async function runApiEndpointWorkflow(apiUrl, opts) {
   let state = await resolveApiEndpointWorkflowState(apiUrl, opts);
   const operations = [];
+  let completedEphemeralStepId = null;
   if (opts.apply || opts.applyAll) {
     const maxSteps = opts.applyAll ? 10 : 1;
     for (let i = 0; i < maxSteps; i += 1) {
       if (state.blocked || !state.firstRunnable) break;
       const operation = await applyApiEndpointWorkflowStep(apiUrl, state, opts, opts.stepId);
       operations.push(operation);
+      if (state.firstRunnable.id === 'smoke_test') {
+        completedEphemeralStepId = 'smoke_test';
+        break;
+      }
       if (!opts.applyAll) break;
       state = await resolveApiEndpointWorkflowState(apiUrl, opts);
     }
   }
   const latestState = operations.length ? await resolveApiEndpointWorkflowState(apiUrl, opts) : state;
+  const latestSteps = completedEphemeralStepId
+    ? latestState.steps.map((item) => (
+      item.id === completedEphemeralStepId
+        ? { ...item, status: 'completed', result: 'passed' }
+        : item
+    ))
+    : latestState.steps;
+  const nextSteps = completedEphemeralStepId
+    ? latestState.nextSteps.filter((item) => item.stepId !== completedEphemeralStepId)
+    : latestState.nextSteps;
   return {
     action: operations.length ? 'api_endpoint_workflow_advanced' : 'api_endpoint_workflow_planned',
     endpoint: latestState.endpoint,
     scriptValidation: latestState.scriptValidation,
-    steps: latestState.steps,
+    steps: latestSteps,
     operations,
-    complete: latestState.steps.every((item) => ['completed', 'skipped'].includes(item.status)),
-    nextSteps: latestState.nextSteps,
+    complete: latestSteps.every((item) => ['completed', 'skipped'].includes(item.status)),
+    nextSteps,
     cleanupHints: latestState.endpoint.routeId
       ? [
         `Preview delete route handler with delete_record({ tableName: "enfyra_route_handler", id: ${JSON.stringify(latestState.endpoint.handlerId)} }) before cleanup.`,

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 } = {}) {