formlab-mcp 0.5.0 → 0.5.2

package/README.md

@@ -39,8 +39,8 @@ Ask Claude (or another MCP client) things like:
 | `get_batch` | Full record + actual composition + samples + blend lineage |
 | `list_samples` | Filtered list of physical specimens |
 | `get_sample` | Full record + canonical variant + test reports + blend lineage |
-| `list_test_results` | Filtered list of test reports |
-| `get_test_result` | Full record + every measurement value |
+| `list_test_results` | Filtered list of test reports (by sample, parameter, **measured-value range** (`value_min`/`value_max`), date, or lab) |
+| `get_test_result` | Full report: every measurement's value, spec, and the **resolved instrument** (`instrumentSource`: row / method / run) |
 | `get_doe_matrix` | Pivot matrix (CSV by default) — rows × ingredients × parameters |
 | `find_failures` | Pareto-style: parameters that fail acceptance most often |
 | `get_coverage_matrix` | Which formulations × parameters have been measured |
@@ -93,23 +93,22 @@ The MCP server watches the file — re-export from FormLab and the next tool cal
 Instead of an export file, point the server at your **live cloud workspace** so it's always current.
 
 1. In FormLab (Pro): **Settings → Account → AI tools (MCP) → Connect…**
-2. Copy the generated config and paste it into Claude Desktop (it merges with the file-mode example below).
+2. Click **Create token**, copy the generated config, and paste it into Claude Desktop.
 
-The config sets these env vars (which switch the server into cloud mode):
+The config sets a single env var, which switches the server into cloud mode:
 
 | Env var | Value |
 |---|---|
-| `FORMLAB_SUPABASE_URL` | your Supabase project URL (public) |
-| `FORMLAB_SUPABASE_ANON_KEY` | publishable/anon key (public) |
-| `FORMLAB_REFRESH_TOKEN` | your session refresh token — **a credential** |
-| `FORMLAB_WORKSPACE_ID` | (optional) workspace to read; defaults to your own |
+| `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` |
 
-When `FORMLAB_REFRESH_TOKEN` + URL + key are present, the server reads the workspace directly (RLS-scoped to you), re-fetching every `FORMLAB_REFRESH_SECONDS`. It's **read-only**.
+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.
 
-> ⚠ **Security.** The refresh token grants read access to your account — treat the config like a password (don't share or commit it). To revoke: FormLab → Account → *Sign out of all devices*. A dedicated, revocable, **read-only** MCP token is the planned hardening (needs a small backend: a tokens table + an Edge Function to mint/validate).
+> **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*.
 
-Cloud mode needs `@supabase/supabase-js` (a normal dependency) — `npm install` in this folder, or `npx -y formlab-mcp` pulls it automatically.
+Cloud mode has no extra dependency — it's a plain `fetch`.
 
 ## Wire it up to Claude Desktop
 

package/index.js

@@ -114,7 +114,7 @@ const TOOLS = [
 ];
 
 const server = new Server(
-  { name: 'formlab-mcp', version: '0.5.0' },
+  { name: 'formlab-mcp', version: '0.5.2' },
   { capabilities: { tools: {} } }
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formlab-mcp",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "mcpName": "io.github.juliu1980/formlab-mcp",
   "description": "Read-only Model Context Protocol server for FormLab \u2014 lets Claude (and other MCP clients) read and analyze your FormLab data, from a local export file OR your live cloud workspace.",
   "type": "module",

package/server.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.juliu1980/formlab-mcp",
-  "description": "Read-only MCP for FormLab — talk to your local lab notebook via Claude. Data stays local.",
-  "version": "0.1.7",
-  "websiteUrl": "https://formvix.com",
+  "description": "Read-only MCP for FormLab — let Claude query your formulation lab. Free reads a local export; Pro connects to your live cloud workspace with a dedicated read-only token.",
+  "version": "0.5.2",
+  "websiteUrl": "https://formvix.com/mcp",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
     "source": "github",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.1.7",
+      "version": "0.5.2",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"
@@ -22,11 +22,19 @@
         {
           "type": "positional",
           "name": "exportPath",
-          "description": "Absolute path to a FormLab export JSON file (Data → Export JSON in the FormLab UI).",
-          "isRequired": true,
+          "description": "File mode: absolute path to a FormLab export JSON (Data → Export JSON). Omit when using cloud mode (set FORMLAB_MCP_TOKEN instead).",
+          "isRequired": false,
           "format": "filepath",
           "value": "/path/to/formlab-export.json"
         }
+      ],
+      "environmentVariables": [
+        {
+          "name": "FORMLAB_MCP_TOKEN",
+          "description": "Cloud mode: a dedicated read-only, revocable token (flmcp_…) minted in FormLab → Settings → Account → AI tools (MCP) → Connect. Reads your live workspace, scoped to you by row-level security. Omit for file mode.",
+          "isRequired": false,
+          "isSecret": true
+        }
       ]
     }
   ]

package/tools/analytics.js

@@ -9,6 +9,34 @@
 
 import { getStore, resolveById, flattenComposition } from '../data.js';
 
+// Which instrument produced a measurement. Mirrors the app's _trMeasInstrument:
+// a measurement's raw `instrument` is usually EMPTY because blank means inherit,
+// so returning the stored field alone would be near-useless here. Resolve the
+// same cascade the UI shows, and report the source so a consumer can tell a
+// recorded fact from an inherited default:
+//   'row'    — the measurement names its own instrument
+//   'method' — from the parameter's Test Method equipment (the usual case)
+//   'run'    — the report-level default (an assumption, not evidence)
+function _resolveInstrument(m, t, db) {
+  if (m && (m.instrument || m.equipmentId)) {
+    return { instrument: m.instrument || '', equipmentId: m.equipmentId || null, instrumentSource: 'row' };
+  }
+  const params = (db && db.parameters) || [];
+  let pm = null;
+  if (m && m.parameterId) pm = params.find(p => p && p.id === m.parameterId) || null;
+  if (!pm && m) {
+    const nm = String(m.parameter || '').trim().toLowerCase();
+    if (nm) pm = params.find(p => p && String(p.name || '').trim().toLowerCase() === nm) || null;
+  }
+  if (pm && (pm.equipment || pm.equipmentId)) {
+    return { instrument: pm.equipment || '', equipmentId: pm.equipmentId || null, instrumentSource: 'method' };
+  }
+  if (t && (t.instrument || t.equipmentId)) {
+    return { instrument: t.instrument || '', equipmentId: t.equipmentId || null, instrumentSource: 'run' };
+  }
+  return { instrument: '', equipmentId: null, instrumentSource: null };
+}
+
 function _trimTest(t, samplesById) {
   if (!t) return null;
   const s = t.sampleId ? samplesById.get(t.sampleId) : null;
@@ -20,12 +48,16 @@ function _trimTest(t, samplesById) {
     testDate: t.testDate || '',
     performedBy: t.performedBy || '',
     lab: t.lab || '',
+    instrument: t.instrument || '',          // run-level default; measurements may override
+    equipmentId: t.equipmentId || null,
+    controlSample: !!t.controlSample,        // a re-measured reference — the valid basis for drift
     measurementCount: (t.measurements || []).length,
     parameters: [...new Set((t.measurements || []).map(m => m.parameter).filter(Boolean))],
   };
 }
 
-function _trimMeasurement(m) {
+function _trimMeasurement(m, t, db) {
+  const ins = _resolveInstrument(m, t, db);
   return {
     parameter: m.parameter || '',
     value: m.value ?? null,
@@ -34,18 +66,21 @@ function _trimMeasurement(m) {
     pointCount: Array.isArray(m.points) ? m.points.length : 0,
     binCount: Array.isArray(m.bins) ? m.bins.length : 0,
     acceptanceCriteria: m.acceptanceCriteria || null,
+    ...ins,                                   // instrument, equipmentId, instrumentSource
   };
 }
 
 const list_test_results = {
   definition: {
     name: 'list_test_results',
-    description: 'List test result reports, optionally filtered by sample, parameter, date range, or lab. Returns metadata + parameters tested. Use get_test_result for full measurement values.',
+    description: 'List test result reports, optionally filtered by sample, parameter, measured-value range, date range, or lab. Combine parameter + value_min/value_max to find reports whose measurement is in range (the "find by results" query, e.g. parameter="Viscosity", value_min=800, value_max=3000). Returns metadata (incl. the run-level instrument and controlSample flag) + parameters tested; use get_test_result for per-measurement values and their resolved instruments.',
     inputSchema: {
       type: 'object',
       properties: {
         sample_id: { type: 'string', description: 'Filter to results for this sample (id or UID).' },
         parameter: { type: 'string', description: 'Filter to results that include this parameter (case-insensitive substring).' },
+        value_min: { type: 'number', description: 'Only reports where the parameter (above) measured >= this value. Use with `parameter`; applies to any measurement if `parameter` is omitted.' },
+        value_max: { type: 'number', description: 'Only reports where the parameter (above) measured <= this value. Use with `parameter`; applies to any measurement if `parameter` is omitted.' },
         since_date: { type: 'string', description: 'ISO date — only reports on/after this date.' },
         until_date: { type: 'string', description: 'ISO date — only reports on/before this date.' },
         lab: { type: 'string', description: 'Filter by lab name (case-insensitive substring).' },
@@ -69,8 +104,19 @@ const list_test_results = {
       if (args.since_date && (t.testDate || '') < args.since_date) return false;
       if (args.until_date && (t.testDate || '') > args.until_date) return false;
       if (args.lab && !norm(t.lab).includes(norm(args.lab))) return false;
-      if (args.parameter) {
-        const found = (t.measurements || []).some(m => norm(m.parameter).includes(norm(args.parameter)));
+      const hasRange = args.value_min != null || args.value_max != null;
+      if (args.parameter || hasRange) {
+        const pn = norm(args.parameter);
+        const found = (t.measurements || []).some(m => {
+          if (args.parameter && !norm(m.parameter).includes(pn)) return false;
+          if (hasRange) {
+            const v = parseFloat(m.value);
+            if (!Number.isFinite(v)) return false;
+            if (args.value_min != null && v < args.value_min) return false;
+            if (args.value_max != null && v > args.value_max) return false;
+          }
+          return true;
+        });
         if (!found) return false;
       }
       return true;
@@ -86,7 +132,7 @@ const list_test_results = {
 const get_test_result = {
   definition: {
     name: 'get_test_result',
-    description: 'Get full details for a single test result report including every measurement\'s value, unit, type, and acceptance criteria. Accepts internal id or UID.',
+    description: 'Get full details for a single test result report: every measurement\'s value, unit, type, acceptance criteria, and the INSTRUMENT that produced it. instrument is RESOLVED (measurement override → the parameter\'s Test Method equipment → the report default) with instrumentSource telling you which — treat source "run" as an inherited assumption, not evidence. Accepts internal id or UID.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -102,7 +148,7 @@ const get_test_result = {
     return {
       ..._trimTest(t, indexes.samplesById),
       notes: t.notes || '',
-      measurements: (t.measurements || []).map(_trimMeasurement),
+      measurements: (t.measurements || []).map(m => _trimMeasurement(m, t, getStore().db)),
     };
   },
 };

package/tools/library.js

@@ -176,7 +176,7 @@ const list_test_methods = {
 const get_test_method = {
   definition: {
     name: 'get_test_method',
-    description: 'Get one Test Method by UID (e.g. PARAM-001) or id — full definition including SOP / sample prep / equipment / calculation / acceptance spec, plus sibling methods that share its analyte (the same property measured at other conditions).',
+    description: 'Get one Test Method by UID (e.g. PARAM-001) or id — full definition including SOP / sample prep / equipment / calculation / acceptance spec, plus sibling methods that share its analyte (the same property measured at other conditions) and the Test Panels that use this method.',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Test Method UID or internal id.' } },
@@ -191,7 +191,13 @@ const get_test_method = {
     const siblings = an
       ? (db.parameters || []).filter(x => x.id !== p.id && _norm(x.analyte) === an).map(x => x.uid || x.name).slice(0, 20)
       : [];
-    return { ...(_trimMethod(p, { full: true })), analyteSiblings: siblings };
+    // Reverse usage: which Test Panels reference this method (by id, else by name).
+    const nm = _norm(p.name);
+    const usingPanels = (db.templates || []).filter(t => (t.parameters || []).some(row =>
+      (row.parameterId && row.parameterId === p.id) ||
+      (!row.parameterId && _norm(row.parameter || row.name) === nm)
+    )).map(t => t.uid || t.name).slice(0, 40);
+    return { ...(_trimMethod(p, { full: true })), analyteSiblings: siblings, usingPanels };
   },
 };
 
@@ -278,8 +284,10 @@ function _trimPanelParam(row, db) {
     parameterId: row.parameterId || null,
     methodUid: method ? (method.uid || null) : null,
     unit: row.unit || (method && method.defaultUnit) || '',
-    ...(row.spec ? { spec: row.spec } : {}),
+    ...(row.spec || row.specRaw ? { spec: row.spec || row.specRaw } : {}),
     ...(row.method ? { method: row.method } : {}),
+    ...(row.required ? { required: true } : {}),
+    ...(row.minReps && row.minReps > 1 ? { minReps: row.minReps } : {}),
   };
 }