formlab-mcp 0.6.59 → 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.59",
+  "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.59",
+  "version": "0.6.60",
   "websiteUrl": "https://formvix.com/mcp",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.6.59",
+      "version": "0.6.60",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"