formlab-mcp 0.6.32 → 0.6.34

package/README.md

@@ -45,13 +45,13 @@ Ask Claude (or another MCP client) things like:
 | `get_sample` | Full record + canonical variant + test reports + blend lineage |
 | `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, any per-measurement run **conditions**, and the **resolved instrument** (`instrumentSource`: row / method / run). Complex types carry a `representative` (time-series → final, distribution → D50); a time series adds `aggregated` (per-timestamp mean ± sd) and `pointReplicates` (repeat readings at one `t`). Report-level `seriesReplicates` lists parameters measured 2+ times as separate rows — point vs series replicates are distinct. Each measurement also gives its **effective spec** (`effectiveSpec`, `specSource`: override / template / parameter / none) and `passFail` — panel and Test Method specs apply exactly as in the app, and every pass/fail count across the tools uses the same rule |
-| `get_doe_matrix` | Pivot matrix (CSV by default) — rows × ingredients × parameters |
+| `get_doe_matrix` | Pivot matrix (CSV by default) — rows × ingredients × parameters. A parameter measured under two or more **run conditions** (storage 25 °C vs 40 °C) is one column per condition (`pH`, `pH · 40 °C`; the bare name is the base arm), never averaged together — same columns as the app's DOE Matrix |
 | `find_failures` | Parameters ranked by failure **rate** (failing ÷ all readings; replicates in one report count once), `lowN` flag under 5 readings, plus formulations ranked by share of failing reports — same numbers as the app's Test Analytics → Failures |
-| `get_coverage_matrix` | TEST coverage by formulation, batch or sample (`grain`) × parameter. Each cell is the **latest** reading by test date (same-day reports averaged, any fail → fail) with its date and how many reports measured it — same rollup as the app's Test Analytics → Coverage |
+| `get_coverage_matrix` | TEST coverage by formulation, batch or sample (`grain`) × parameter. Each cell is the **latest** reading by test date (same-day reports averaged, any fail → fail) with its date and how many reports measured it; one column per **run condition** when a parameter was measured under two or more — same rollup as the app's Test Analytics → Coverage |
 | `compare_batches` | Reproducibility of 2+ runs (ideally of one formula): each run's **yield %**, actual produced mass, cost/kg; per-ingredient **drift** across the runs vs the formula's proposed wt-%; and the biggest **outlier** run. `basis`: `wt_percent` (default) or `amount` |
 | `get_batch_pivot` | Production analytics — aggregate batches by `group_by` (formula / status / month / prepared_by / project) × `metric` (count, avg_yield_pct, total_produced_kg, avg_cost_per_batch, total_samples, total_tests), with share + total for additive metrics. Optional `batch_uids` scope + `status` filter |
 | `get_project_pivot` | Portfolio analytics — aggregate projects by `group_by` (status / phase / priority / business_unit / site / customer / lead, or `cf:<custom field>`) × `metric` (count, total_formulas / batches / samples, total_cost, avg_formulas / batches / cost_per_batch), rolling child activity + cost up by any project attribute. Optional `project_uids` scope |
-| `get_stability` | Grounded stability / shelf-life analysis for a formulation, sample or batch × parameter (auto-detected): time-series, drift (per-month slope + R²), an I-chart (mean ±3σ + out-of-control points), spec status, and an ICH-Q1E-flavored projected shelf life (point + 95%-CI crossing), split by storage condition |
+| `get_stability` | Grounded stability / shelf-life analysis for a formulation, sample or batch × parameter (auto-detected): time-series, drift (per-month slope + R²), an I-chart (mean ±3σ + out-of-control points), spec status, and an ICH-Q1E-flavored projected shelf life (point + 95%-CI crossing), all on **one point per test date per run condition** (replicates averaged, never separate time points), split by storage condition |
 | `get_design_space` | COMPOSITION design space for one project: which ingredients vary and over what observed wt-% ranges (ranked), an occupied-region summary ("where you've been"), the biggest untested **interior gap** as ready-to-seed DOE ranges (a combination you could have made but skipped), and an optional standardised **2-component PCA** of all varying ingredients — loadings, variance-explained, scree, and a full-dimensional gap. Matches the in-app Design Space Viewer exactly. Answers *"where haven't I explored?"* / *"what should I formulate next?"* |
 | `list_doe_designs` | Saved DOE designs — the *recipe* behind each batch of runs: design type, factors + ranges, constraints, run count, D-efficiency. Filters: `project`, `design_type`, `constrained_only`, `name_contains` |
 | `get_doe_design` | One design in full: constraints in plain language, the model it was optimised for, generation settings (run budget, replicates, centre points, seed) and the complete run matrix with the formulation each run became |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.32",
+  "version": "0.6.34",
   "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

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.juliu1980/formlab-mcp",
   "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.6.32",
+  "version": "0.6.34",
   "websiteUrl": "https://formvix.com/mcp",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.6.32",
+      "version": "0.6.34",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tools/analytics.js

@@ -226,7 +226,7 @@ const get_test_result = {
 const get_doe_matrix = {
   definition: {
     name: 'get_doe_matrix',
-    description: 'Build a Design-of-Experiments style pivot matrix: rows = formulations (or samples / batches / tests), columns = composition wt-% per ingredient + aggregated test-parameter values. Same shape as the FormLab DOE Matrix view. Returns CSV when format=csv (default) for compact LLM consumption, or structured JSON when format=json.',
+    description: 'Build a Design-of-Experiments style pivot matrix: rows = formulations (or samples / batches / tests), columns = composition wt-% per ingredient + aggregated test-parameter values. Same shape as the FormLab DOE Matrix view. A parameter measured under two or more RUN CONDITIONS (e.g. storage 25 °C vs 40 °C) is one column per condition — "pH · 40 °C" — and the bare parameter column is the base arm (readings with no condition, else the condition with the most readings); they are different responses, never averaged together. Returns CSV when format=csv (default) for compact LLM consumption, or structured JSON when format=json.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -335,11 +335,22 @@ const get_doe_matrix = {
       const ing = indexes.ingredientsById.get(id);
       return { id, label: (ing?.name || id) + ' (%)' };
     });
-    const paramCols = [...parameters].map(p => ({ id: p, label: p }));
+    // One column per parameter, or per (parameter, run condition) when it was
+    // measured under two or more conditions — see _mcpArmNames.
+    const armNames = _mcpArmNames(rows.flatMap(r => r.measurements
+      .filter(m => m && m.parameter && parameters.has(m.parameter))
+      .map(m => ({ parameter: m.parameter, m }))));
+    const paramCols = [];
+    [...parameters].forEach(p => {
+      const arms = armNames.get(p);
+      if (!arms) { paramCols.push({ id: p, cond: null, label: p }); return; }
+      arms.forEach((label, sig) => paramCols.push({ id: p, cond: sig, label }));
+    });
 
-    // 4) Aggregate measurements per param per row (mean of numeric scalar values)
-    const cellParamValue = (r, param) => {
-      const ms = r.measurements.filter(m => m.parameter === param);
+    // 4) Aggregate measurements per column per row (mean of numeric scalar
+    //    values), reading only the column's own run condition when split.
+    const cellParamValue = (r, col) => {
+      const ms = r.measurements.filter(m => m.parameter === col.id && (col.cond == null || _mcpCondSig(m) === col.cond));
       if (!ms.length) return null;
       const nums = ms.map(m => parseFloat(m.value)).filter(v => isFinite(v));
       if (!nums.length) return ms[0].value ?? null;
@@ -360,7 +371,7 @@ const get_doe_matrix = {
         rows: limitedRows.map(r => ({
           label: r.label,
           ingredientPct: Object.fromEntries(ingCols.map(c => [c.label, r.composition.get(c.id) ?? null])),
-          parameterMean: Object.fromEntries(paramCols.map(c => [c.label, cellParamValue(r, c.id)])),
+          parameterMean: Object.fromEntries(paramCols.map(c => [c.label, cellParamValue(r, c)])),
         })),
       };
     }
@@ -377,7 +388,7 @@ const get_doe_matrix = {
       const cells = [
         r.label,
         ...ingCols.map(c => r.composition.get(c.id) ?? ''),
-        ...paramCols.map(c => cellParamValue(r, c.id) ?? ''),
+        ...paramCols.map(c => cellParamValue(r, c) ?? ''),
       ];
       lines.push(cells.map(escCSV).join(','));
     });
@@ -414,6 +425,57 @@ function _mcpCondSig(m) {
   if (!c || typeof c !== 'object') return '';
   return Object.keys(c).filter(k => c[k] != null && c[k] !== '').sort().map(k => `${k}=${c[k]}`).join('|');
 }
+// ---- Run-condition ARMS (mirror the app, FormLab 1.16.18 build 24h–24i) ----
+// A parameter measured under two or more run conditions (storage 25 °C vs
+// 40 °C, first vs second heat) is one column per condition in the DOE Matrix
+// and the Coverage matrix: an ambient arm and an accelerated one are different
+// responses, never averaged. The bare parameter name keeps the BASE arm — the
+// readings with no condition when there are any, otherwise the arm with the
+// most readings (the arm a bare `pH` means in the app's search) — and the
+// others read "pH · 40 °C". Same rule and the same tag shortening as the app
+// (js/utils.js flCondTags), so column names match what the user sees.
+function _mcpCondLabel(m) {
+  const c = m && m.conditions;
+  if (!c || typeof c !== 'object') return '';
+  return Object.entries(c).filter(([, v]) => v != null && v !== '').map(([k, v]) => `${k} ${v}`).join(' · ');
+}
+function _mcpCondTags(conds) {
+  const named = conds.filter(Boolean);
+  let pre = '';
+  if (named.length > 1) {
+    const first = named[0];
+    let i = 0;
+    while (i < first.length && named.every(c => c[i] === first[i])) i++;
+    pre = first.slice(0, i);
+    pre = pre.slice(0, pre.lastIndexOf(' ') + 1);
+  }
+  const tags = conds.map(c => c ? (c.slice(pre.length) || c) : 'no condition');
+  const lead = tags.map(t => t.split(/\s+[\/·]\s+/)[0]);
+  return (new Set(lead).size === lead.length) ? lead : tags;
+}
+// items: [{ parameter, m }] → Map(parameter → Map(condSig → column name)),
+// only for parameters with two or more arms.
+function _mcpArmNames(items) {
+  const arms = new Map();
+  for (const it of items) {
+    const sig = _mcpCondSig(it.m);
+    if (!arms.has(it.parameter)) arms.set(it.parameter, new Map());
+    const a = arms.get(it.parameter);
+    const cur = a.get(sig) || { n: 0, m: it.m };
+    cur.n++; a.set(sig, cur);
+  }
+  const out = new Map();
+  arms.forEach((a, param) => {
+    if (a.size < 2) return;
+    const keys = [...a.keys()];
+    const base = a.has('') ? '' : keys.slice().sort((x, y) => (a.get(y).n - a.get(x).n) || x.localeCompare(y))[0];
+    const ordered = [base, ...keys.filter(k => k !== base).sort((x, y) => x.localeCompare(y))];
+    const tags = _mcpCondTags(ordered.map(k => k ? _mcpCondLabel(a.get(k).m) : ''));
+    out.set(param, new Map(ordered.map((k, i) => [k, i === 0 ? param : `${param} · ${tags[i]}`])));
+  });
+  return out;
+}
+
 function _mcpFlattenReadings(tests, indexes, paramFilter) {
   const norm = (s) => String(s || '').toLowerCase();
   const groups = new Map(); const order = [];
@@ -613,7 +675,7 @@ function _evalPassFail(m, templateId, db) {
 const get_coverage_matrix = {
   definition: {
     name: 'get_coverage_matrix',
-    description: 'Coverage matrix matching the app\'s Test Analytics → Coverage: rows = sample, batch or formulation (grain), columns = parameters. Each cell is the LATEST reading by test date; readings from several reports on that same date are averaged and fail if any of them fails. Each cell also gives latestDate, reportsAveraged and nReports (how many reports measured it). Empty = never tested. Use for "what\'s untested", "what\'s the current value" and "what\'s been measured many times".',
+    description: 'Coverage matrix matching the app\'s Test Analytics → Coverage: rows = sample, batch or formulation (grain), columns = parameters — one column per RUN CONDITION when a parameter was measured under two or more (e.g. "pH" and "pH · 40 °C"; the bare name is the base arm), never averaged together. Each cell is the LATEST reading by test date; readings from several reports on that same date are averaged and fail if any of them fails. Each cell also gives latestDate, reportsAveraged and nReports (how many reports measured it). Empty = never tested. Use for "what\'s untested", "what\'s the current value" and "what\'s been measured many times".',
     inputSchema: {
       type: 'object',
       properties: {
@@ -650,7 +712,7 @@ const get_coverage_matrix = {
     if (fmt === 'json') {
       return {
         grain, rowCount: sorted.length, parameterCount: paramCols.length, parameters: paramCols,
-        rule: 'cell = latest reading by test date; same-date reports averaged (any fail → fail)',
+        rule: 'cell = latest reading by test date; same-date reports averaged (any fail → fail); one column per run condition, never averaged across',
         rows: sorted.map(r => ({ [grain]: r.label, id: r.uid, cells: Object.fromEntries([...r.cells.entries()].sort()) })),
       };
     }
@@ -671,6 +733,15 @@ const get_coverage_matrix = {
 
 // Latest-date rollup (mirrors the app's _taCoverageRows).
 function _mcpCoverageRows(flat, grain, indexes) {
+  // One column per run condition first (see _mcpArmNames), so "latest" never
+  // means whichever storage arm was pulled last and a shared date never
+  // averages ambient with accelerated.
+  const armNames = _mcpArmNames(flat);
+  if (armNames.size) flat = flat.map(r => {
+    const map = armNames.get(r.parameter);
+    const nm = map && map.get(_mcpCondSig(r.m));
+    return (!nm || nm === r.parameter) ? r : { ...r, parameter: nm };
+  });
   const rows = new Map();
   for (const r of flat) {
     let rec = null, label = '';
@@ -693,8 +764,12 @@ function _mcpCoverageRows(flat, grain, indexes) {
       const nums = list.map(x => x.numeric).filter(v => v != null && isFinite(v));
       const mean = nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : null;
       const pf = list.some(x => x.pf === 'fail') ? 'fail' : list.some(x => x.pf === 'pass') ? 'pass' : list[0].pf;
+      // Replicate means carry float dust ((5.9 + 5.9 + 5.9) / 3 = 5.900000000000001);
+      // an agent should read the number the user sees. 12 significant digits
+      // keeps every real value.
+      const tidy = (v) => (typeof v === 'number' && isFinite(v)) ? Number(v.toPrecision(12)) : v;
       row.cells.set(param, {
-        value: list.length === 1 ? (list[0].numeric != null ? list[0].numeric : list[0].value) : (mean != null ? mean : list[0].value),
+        value: tidy(list.length === 1 ? (list[0].numeric != null ? list[0].numeric : list[0].value) : (mean != null ? mean : list[0].value)),
         unit: list[0].unit, pf: (pf === 'pass' || pf === 'fail') ? pf : null,
         latestDate: date || null, reportsAveraged: list.length, nReports: row.reports.get(param).size,
       });
@@ -1013,7 +1088,7 @@ function _shelfLifeAssess(sl, targetMonths, now) {
 const get_stability = {
   definition: {
     name: 'get_stability',
-    description: 'Grounded stability / shelf-life analysis for one entity × parameter — the deterministic numbers behind the Stability & Trends view. Pass a formulation (pools all its samples), a sample (that sample over time), or a batch (pools its samples) by id or UID, plus a parameter name. Returns the time series, drift (per-month slope + R²), an individuals control chart (mean ± 3σ + out-of-control points), spec status, and an ICH-flavored projected shelf life (linear extrapolation to the spec crossing: point estimate + the conservative 95%-confidence-bound crossing). When measurements carry run conditions (e.g. Storage 25 °C vs 40 °C) it splits into one series per condition — a true accelerated-vs-ambient comparison. Use these figures directly; do not re-derive the regression.',
+    description: 'Grounded stability / shelf-life analysis for one entity × parameter — the deterministic numbers behind the Stability & Trends view. Pass a formulation (pools all its samples), a sample (that sample over time), or a batch (pools its samples) by id or UID, plus a parameter name. Returns the time series, drift (per-month slope + R²), an individuals control chart (mean ± 3σ + out-of-control points), spec status, and an ICH-flavored projected shelf life (linear extrapolation to the spec crossing: point estimate + the conservative 95%-confidence-bound crossing). When measurements carry run conditions (e.g. Storage 25 °C vs 40 °C) it splits into one series per condition — a true accelerated-vs-ambient comparison. A point is one TEST DATE: every reading taken that day under that condition is averaged (points = test dates, readings = the raw count), so replicates never count as separate time points in the drift, control chart or shelf-life fit — the same points as the app. Use these figures directly; do not re-derive the regression.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1068,7 +1143,7 @@ const get_stability = {
         }
         const cond = (m.conditions && Object.keys(m.conditions).length)
           ? Object.entries(m.conditions).map(([k, v]) => `${k} ${v}`).join(' · ') : '';
-        points.push({ date, value, cond, spec: sp });
+        points.push({ date, day: dStr, value, cond, spec: sp });
       });
     });
     const specList = [...specByKey.values()].map(e => ({ min: e.min, max: e.max, readings: e.readings, sources: [...e.sources] }));
@@ -1079,7 +1154,21 @@ const get_stability = {
       const pdef = (db.parameters || []).find(p => (p.name || '').trim().toLowerCase() === paramLc);
       if (pdef && pdef.acceptanceCriteria) { specMin = pdef.acceptanceCriteria.min ?? null; specMax = pdef.acceptanceCriteria.max ?? null; }
     }
-    points.sort((a, b) => a.date - b.date);
+    // ONE POINT PER TEST DATE PER RUN CONDITION — the mean of every reading
+    // taken that day under that condition — exactly as the app's Stability view
+    // (FormLab build 24k). Replicates are not separate time points: counting a
+    // triplicate as three consecutive observations took the control chart's
+    // sigma from within-day differences (Clarifying Shampoo's ambient pH: 10
+    // out-of-control points on 53 readings, 1 on its 18 test dates) and gave
+    // the drift and shelf-life fits degrees of freedom the study does not have.
+    const byDay = new Map();
+    points.forEach(p => { const k = p.day + '\u0000' + p.cond; if (!byDay.has(k)) byDay.set(k, []); byDay.get(k).push(p); });
+    points.length = 0;
+    byDay.forEach(g => {
+      const value = g.reduce((a, r) => a + r.value, 0) / g.length;
+      points.push({ date: new Date(g[0].day), value, cond: g[0].cond, spec: (g.find(r => r.spec) || {}).spec || null, readings: g.length });
+    });
+    points.sort((a, b) => (a.date - b.date) || a.cond.localeCompare(b.cond));
     if (!points.length) return { error: `No dated "${args.parameter}" measurements on ${entity.uid || entity.id}.` };
 
     const spec = { min: specMin, max: specMax };
@@ -1094,7 +1183,7 @@ const get_stability = {
     const analyze = (pts) => {
       const ys = pts.map(p => p.value);
       const n = ys.length;
-      const out = { points: n, from: pts[0].date.toISOString().slice(0, 10), to: pts[n - 1].date.toISOString().slice(0, 10), values: ys.map(v => _round(v, 6)), latest: _round(ys[n - 1], 6) };
+      const out = { points: n, readings: pts.reduce((a, p) => a + (p.readings || 1), 0), from: pts[0].date.toISOString().slice(0, 10), to: pts[n - 1].date.toISOString().slice(0, 10), values: ys.map(v => _round(v, 6)), latest: _round(ys[n - 1], 6) };
       if (n < 2) { out.note = 'Fewer than 2 points — no trend/shelf-life.'; return out; }
       // Drift on real elapsed months (not point order), like the shelf-life
       // projection and the app's Stability view: uneven ICH schedules
@@ -1154,7 +1243,7 @@ const get_stability = {
   },
 };
 
-export { _evalPassFail, _resolveSpec, _shelfLife, _shelfLifeAssess };
+export { _evalPassFail, _resolveSpec, _shelfLife, _shelfLifeAssess, _mcpCondTags, _mcpArmNames };
 export const tools = {
   list_test_results,
   get_test_result,