formlab-mcp 0.6.58 → 0.6.60

package/README.md

@@ -124,9 +124,9 @@ The config sets a single env var, which switches the server into cloud mode:
 | `FORMLAB_MCP_TOKEN` | a dedicated, **read-only**, revocable token (`flmcp_…`) |
 | `FORMLAB_SUPABASE_URL` | (optional) override the backend URL — defaults to production |
 | `FORMLAB_SUPABASE_ANON_KEY` | (optional) override the publishable key — defaults to production |
-| `FORMLAB_REFRESH_SECONDS` | (optional) poll interval, default `60` |
+| `FORMLAB_REFRESH_SECONDS` | (optional) how old the copy may be when a tool is called before it's fetched again, default `300` (5 minutes). Nothing is fetched while no tool is called |
 
-When `FORMLAB_MCP_TOKEN` is present, the server POSTs it to FormLab's `mcp-data` Edge Function, which returns your workspace scoped to you by row-level security and re-fetches every `FORMLAB_REFRESH_SECONDS`. It's **read-only** — enforced at the database (a dedicated `mcp_readonly` Postgres role with `SELECT`-only grants), not by trust.
+When `FORMLAB_MCP_TOKEN` is present, the server POSTs it to FormLab's `mcp-data` Edge Function, which returns your workspace scoped to you by row-level security. It's fetched once at start, then again only when a tool is called and the copy is older than `FORMLAB_REFRESH_SECONDS` (5 minutes by default); an idle server sends nothing. It's **read-only** — enforced at the database (a dedicated `mcp_readonly` Postgres role with `SELECT`-only grants), not by trust.
 
 > **Security.** The token grants **read-only** access to one workspace and holds **no account session** — only a SHA-256 hash is stored server-side, and it never rotates. Treat the config like a password (don't share or commit it). **Revoke or re-mint any time** from *Settings → Account → AI tools (MCP) → Connect*.
 
@@ -189,7 +189,7 @@ claude mcp add formlab npx formlab-mcp
 
 **Cloud mode** (`FORMLAB_MCP_TOKEN` set):
 
-- The server sends your token to FormLab's `mcp-data` Edge Function and receives your workspace in return, re-read every 60 seconds (`FORMLAB_REFRESH_SECONDS`).
+- The server sends your token to FormLab's `mcp-data` Edge Function and receives your workspace in return, re-read when a tool is called and the copy is more than 5 minutes old (`FORMLAB_REFRESH_SECONDS`); nothing while idle.
 - The function reads through a dedicated `mcp_readonly` Postgres role with `SELECT`-only grants, and row-level security limits it to the workspace the token was made for.
 - FormLab stores only a SHA-256 hash of the token. It holds no account session and you can revoke it at any time.
 

package/cloud.js

@@ -56,32 +56,41 @@ async function _fetchDb({ url, anonKey, token }) {
   return body;
 }
 
-// Bootstrap: one load up front, then refresh on an interval. Returns
-// { workspaceId, refresh, stop } to mirror the old v1 signature.
-export async function startCloud({ url, anonKey, token, refreshSeconds = 60, onReload } = {}) {
+// Bootstrap: one load up front (it also checks the token), then fetched AGAIN ONLY WHEN A TOOL IS CALLED and the
+// copy is older than `maxAgeSeconds` (FORMLAB_REFRESH_SECONDS, default 300). Until 0.6.60 this re-fetched the
+// whole workspace on a 60 s timer for as long as the server ran, asked or not: two idle copies in Claude Desktop
+// pulled ~6 GB a day from production and took the Supabase project over its egress quota (19 Oct 2026). Idle
+// now costs nothing. Concurrent tool calls share one fetch; a failed refresh keeps the last copy and says so.
+// Returns { workspaceId, refresh, ensureFresh, stop }.
+export async function startCloud({ url, anonKey, token, refreshSeconds = 300, onReload, now = () => Date.now() } = {}) {
   url = url || DEFAULT_SUPABASE_URL;
   anonKey = anonKey || DEFAULT_ANON_KEY;
   if (!token) {
     throw new Error('Cloud mode needs FORMLAB_MCP_TOKEN (mint it from FormLab → Connect to MCP).');
   }
 
-  let workspaceId = null;
+  let workspaceId = null, loadedAt = 0, inflight = null;
   const refresh = async () => {
     const body = await _fetchDb({ url, anonKey, token });
     workspaceId = body.workspaceId || workspaceId;
+    loadedAt = now();
     setStoreFromDb(body.db, { source: 'cloud', workspaceId, schemaName: 'formlab-live', loadedAt: body.loadedAt || new Date().toISOString() });
     if (onReload) { try { onReload(body.db); } catch (_) {} }
     return body.db;
   };
+  // Before a tool answers: fresh enough → nothing; else one fetch, shared by every call waiting on it.
+  const maxAgeMs = Math.max(0, Number(refreshSeconds) || 0) * 1000;
+  const ensureFresh = async () => {
+    if (now() - loadedAt < maxAgeMs) return false;
+    if (!inflight) {
+      inflight = refresh().then(() => true, (e) => {
+        process.stderr.write(`[formlab-mcp] cloud refresh failed, answering from the copy loaded ${Math.round((now() - loadedAt) / 1000)} s ago: ${e.message}\n`);
+        return false;
+      }).finally(() => { inflight = null; });
+    }
+    return inflight;
+  };
 
-  await refresh();   // initial synchronous load before tools accept calls
-
-  let timer = null;
-  if (refreshSeconds > 0) {
-    timer = setInterval(() => {
-      refresh().catch(e => process.stderr.write(`[formlab-mcp] cloud refresh failed: ${e.message}\n`));
-    }, refreshSeconds * 1000);
-    if (timer.unref) timer.unref();
-  }
-  return { workspaceId, refresh, stop: () => { if (timer) clearInterval(timer); } };
+  await refresh();   // initial load before tools accept calls (and an early, clear error for a bad token)
+  return { workspaceId, refresh, ensureFresh, stop: () => {} };
 }

package/index.js

@@ -47,20 +47,24 @@ import * as documents    from './tools/documents.js';
 // FORMLAB_SUPABASE_URL / _ANON_KEY are optional overrides — cloud.js defaults to
 // the public production values, so the config only NEEDS FORMLAB_MCP_TOKEN.
 const CLOUD = !!process.env.FORMLAB_MCP_TOKEN;
+// How old the cloud copy may be when a tool is called before it's fetched again (seconds). Nothing is fetched
+// while no tool is called (0.6.60: no background polling).
+const MAX_AGE_SECONDS = Number(process.env.FORMLAB_REFRESH_SECONDS || 300);
+let cloud = null;
 
 if (CLOUD) {
   try {
-    const h = await startCloud({
+    const h = cloud = await startCloud({
       url:            process.env.FORMLAB_SUPABASE_URL || undefined,
       anonKey:        process.env.FORMLAB_SUPABASE_ANON_KEY || undefined,
       token:          process.env.FORMLAB_MCP_TOKEN,
-      refreshSeconds: Number(process.env.FORMLAB_REFRESH_SECONDS || 60),
+      refreshSeconds: MAX_AGE_SECONDS,
     });
     const s = getStore();
     process.stderr.write(
       `[formlab-mcp] LIVE cloud mode · workspace ${h.workspaceId} · ` +
       `${(s.db.ingredients||[]).length} ingredients · ${(s.db.formulations||[]).length} formulas · ` +
-      `refresh every ${Number(process.env.FORMLAB_REFRESH_SECONDS || 60)}s\n`);
+      `fetched again on use when older than ${MAX_AGE_SECONDS}s (no background polling)\n`);
   } catch (e) {
     process.stderr.write(`[formlab-mcp] cloud mode failed: ${e.message}\n`);
     process.exit(1);
@@ -157,6 +161,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     };
   }
   try {
+    if (cloud) await cloud.ensureFresh();   // cloud mode: refetch only if the copy is older than FORMLAB_REFRESH_SECONDS
     const result = await tool.handler(args || {});
     // All tool handlers return either a plain object/array (auto-
     // serialized as JSON text) or a pre-formatted string. The MCP

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.58",
+  "version": "0.6.60",
   "mcpName": "io.github.juliu1980/formlab-mcp",
   "description": "Read-only Model Context Protocol server for FormLab. Lets Claude and other MCP clients read and analyze your FormLab data, from a local export file or your live cloud workspace.",
   "homepage": "https://formvix.com/mcp",
   "type": "module",
   "bin": {
-    "formlab-mcp": "./index.js"
+    "formlab-mcp": "index.js"
   },
   "main": "index.js",
   "files": [

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.juliu1980/formlab-mcp",
   "description": "Read-only MCP server for FormLab formulation data: a local export file or your live cloud workspace.",
-  "version": "0.6.58",
+  "version": "0.6.60",
   "websiteUrl": "https://formvix.com/mcp",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.6.58",
+      "version": "0.6.60",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tools/analytics.js

@@ -123,7 +123,7 @@ function _trimMeasurement(m, t, db) {
     binCount: Array.isArray(m.bins) ? m.bins.length : 0,
     ...complex,
     acceptanceCriteria: m.acceptanceCriteria || null,
-    // Effective spec + where it came from (override | template | parameter | none)
+    // Effective spec + where it came from (override | template | parameter | result: a Pass / Fail text result judged as written | none)
     // and the app's pass/fail verdict under it.
     ...(() => { const r = _resolveSpec(m, t && t.templateId, db); return { effectiveSpec: r.spec || null, specSource: r.source, passFail: _evalPassFail(m, t && t.templateId, db) }; })(),
     // Captured run conditions this reading was measured under (e.g.
@@ -822,8 +822,19 @@ function _resolveSpec(m, templateId, db) {
     const lib = (store.parameters || []).find(p => p && p.id === m.parameterId);
     if (lib && lib.acceptanceCriteria) return { spec: lib.acceptanceCriteria, source: 'parameter' };
   }
+  // As the app (24b): no spec anywhere, a text result that is itself a verdict (Pass / Fail) is judged as written.
+  if (_measType(m) === 'categorical' && /^(pass|fail)$/.test(_catNorm(m.value))) return { spec: { requiredValue: 'pass', fromResult: true }, source: 'result' };
   return { spec: null, source: 'none' };
 }
+// Text results, as the app (js/views/testing.js, 24b): a spec may accept several results
+// ("=Clear | Slightly hazy"); Pass / Passed and Fail / Failed read as one word each.
+function _catNorm(v) {
+  const s = String(v == null ? '' : v).trim().toLowerCase();
+  return /^pass(ed)?$/.test(s) ? 'pass' : /^fail(ed)?$/.test(s) ? 'fail' : s;
+}
+function _catPasses(required, value) {
+  return String(required == null ? '' : required).split('|').map(_catNorm).filter(Boolean).includes(_catNorm(value));
+}
 
 const _MEAS_TYPES = ['scalar', 'ordinal', 'categorical', 'time_series', 'distribution'];
 function _measType(m) {
@@ -867,7 +878,7 @@ function _evalPassFail(m, templateId, db) {
   if (type === 'categorical') {
     if (!raw) return 'untested';
     if (!crit.requiredValue) return 'no-criteria';
-    return raw.toLowerCase() === String(crit.requiredValue).toLowerCase() ? 'pass' : 'fail';
+    return _catPasses(crit.requiredValue, raw) ? 'pass' : 'fail';
   }
   // As the app (12y): one representative value against the range — a curve's
   // FINAL point, a distribution's statistic named by the spec (crit.stat:

package/vendor/cost.js

@@ -1993,7 +1993,7 @@ function renderWeighoutPanel(w, actuals, formula, copyOnclick, noun) {
   const _woVolTarget = (typeof isVolUnit === 'function') && isVolUnit(w.unit);
   const qsTag = r => (!r.qs) ? '' :
     ` <span style="font-size:9.5px;color:var(--dk-sky-fg, #0369a1);font-weight:600;background:var(--dk-blue-bg, #eff6ff);border:1px solid var(--dk-blue-line, #bfdbfe);border-radius:4px;padding:0 3px;vertical-align:middle;white-space:nowrap" title="${_woVolTarget ? `Balance ingredient — add it up to the ${w.qty} ${esc(w.unit)} mark rather than to this number, then log what actually went in` : 'Balance ingredient, set to hold the batch at its target size'}">${_woVolTarget ? `q.s. to ${w.qty} ${esc(w.unit)}` : 'q.s.'}</span>`;
-  const dColor = rel => rel == null ? '#94a3b8' : (rel < 0.02 ? '#15803d' : rel < 0.10 ? '#b45309' : '#b91c1c');
+  const dColor = rel => rel == null ? 'var(--dk-faint, #94a3b8)' : (rel < 0.02 ? 'var(--dk-green-fg, #15803d)' : rel < 0.10 ? 'var(--dk-amber-fg, #b45309)' : 'var(--dk-red-fg, #b91c1c)');
   // Tint a whole row when it deviates, so off-plan ingredients pop at a glance
   // (matches the composition-% table's row tinting). On-target rows stay white.
   const dRowBg = rel => (rel == null || rel < 0.02) ? '' : (rel < 0.10 ? 'background:var(--dk-amber-bg, #fffbeb)' : 'background:var(--dk-red-bg, #fef2f2)');
@@ -2590,7 +2590,7 @@ function entityCostValueHtml(o) {
     const msg = (why === 'needs-density')
       ? `⚠ add a density to the formula to price ${esc(o.unit || 'this unit')} by mass`
       : `can't convert ${esc(o.unit || 'this unit')} to mass`;
-    const col = (why === 'needs-density') ? '#b45309' : 'var(--text-muted)';
+    const col = (why === 'needs-density') ? 'var(--dk-amber-fg, #b45309)' : 'var(--text-muted)';
     return `<span style="color:var(--text-muted)">—</span> <span style="font-size:11px;color:${col}">${msg}</span>${editBtn}`;
   }
   const breakdown = `<span style="font-size:11px;color:var(--text-muted);margin-left:6px">${esc(String(o.qty))} ${esc(o.unit || '')} × ${money(perKg)}/kg</span>`;