formlab-mcp 0.6.37 → 0.6.39

package/README.md

@@ -51,7 +51,7 @@ Ask Claude (or another MCP client) things like:
 | `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), all on **one point per test date per run condition** (replicates averaged, never separate time points), 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. A ranked-scale (ordinal) or text parameter returns its step / pass-fail series instead: per-condition points, firstFail, latest, scaleShift |
 | `get_design_space` | COMPOSITION design space for one project, several (`projects`) or any formula list (`formulas`, across projects — like the app's Scope → DOE Matrix): 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. Optional `axes` (choose the 2–3 axes), `by_role` (map ingredients summed by primary Function, e.g. Pigment / Solvent / Film Former — no gap, roles aren't DOE factors) and `property` (highest / lowest formula plus the ingredients whose level tracks it, Spearman ρ). Reports formulas that aren't on the map and the spread on it. 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.37",
+  "version": "0.6.39",
   "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.37",
+  "version": "0.6.39",
   "websiteUrl": "https://formvix.com/mcp",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.6.37",
+      "version": "0.6.39",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tools/analytics.js

@@ -164,8 +164,8 @@ const list_test_results = {
         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;
+            const v = _mcpRepNumber(m);   // a curve's final value, not its point count (13a)
+            if (v == null) return false;
             if (args.value_min != null && v < args.value_min) return false;
             if (args.value_max != null && v > args.value_max) return false;
           }
@@ -352,7 +352,9 @@ const get_doe_matrix = {
     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));
+      // The app's DOE Matrix numbers (13a): a curve's final value, a
+      // distribution's D50, an ordinal's 1-based rank; text → its first reading.
+      const nums = ms.map(m => _mcpRepNumber(m, { ordinal: 'rank' })).filter(v => v != null);
       if (!nums.length) return ms[0].value ?? null;
       const mean = nums.reduce((s, v) => s + v, 0) / nums.length;
       return +mean.toFixed(4);
@@ -405,21 +407,96 @@ const get_doe_matrix = {
 // so a parameter measured 3× on one occasion counts once in failure rates and
 // coverage, exactly as Test Analytics does.
 const FAIL_MIN_N = 5;   // app: _TA_FAIL_MIN_N — rates on fewer readings are "low n"
-function _mcpRepNumber(m) {
-  const type = m.type || 'scalar';
-  if (type === 'time_series' && Array.isArray(m.points) && m.points.length) {
+// One number per measurement — the app's flMeasNum (js/utils.js, 13a), kept
+// in step. Never parseFloat(m.value): a saved time series / distribution has
+// "12 points" / "8 bins" there, and an ordinal label "6B" parses to 6.
+//   scalar → value; time_series → opts.ts ('final' default | 'initial' | 'peak');
+//   distribution → opts.dist ('D50' default, a named bin only — no stand-in);
+//   ordinal → null, or with opts.ordinal === 'rank' its 1-based scale position;
+//   categorical → null.
+function _mcpMeasType(m) {
+  const T = ['scalar', 'ordinal', 'categorical', 'time_series', 'distribution'];
+  if (m && m.type && T.includes(m.type)) return m.type;
+  return m && m.valueType === 'Categorical' ? 'categorical' : 'scalar';
+}
+function _mcpRepNumber(m, opts) {
+  const o = opts || {};
+  if (!m) return null;
+  const type = _mcpMeasType(m);
+  if (type === 'time_series') {
+    if (!Array.isArray(m.points) || !m.points.length) return null;
     const agg = _mcpTsAggregate(m.points);
-    const last = agg[agg.length - 1];
-    return last ? last.mean : null;
+    if (!agg.length) return null;
+    const means = agg.map(g => g.mean);
+    const red = o.ts || 'final';
+    const v = red === 'initial' ? means[0] : red === 'peak' ? Math.max(...means) : means[means.length - 1];
+    return isFinite(v) ? v : null;
   }
-  if (type === 'distribution' && Array.isArray(m.bins) && m.bins.length) {
-    const d50 = m.bins.find(b => String(b.label || '').toUpperCase().replace(/\s/g, '') === 'D50');
-    const v = d50 ? parseFloat(d50.value) : NaN;
+  if (type === 'distribution') {
+    if (!Array.isArray(m.bins) || !m.bins.length) return null;
+    const want = String(o.dist || 'D50').toUpperCase();
+    const b = m.bins.find(x => String((x && x.label) || '').toUpperCase().replace(/\s/g, '') === want);
+    const v = b ? parseFloat(b.value) : NaN;
     return isFinite(v) ? v : null;
   }
+  if (type === 'ordinal') {
+    if (o.ordinal !== 'rank' || !Array.isArray(m.scale)) return null;
+    const i = m.scale.map(x => String(x).trim().toUpperCase()).indexOf(String(m.value == null ? '' : m.value).trim().toUpperCase());
+    return i >= 0 ? i + 1 : null;
+  }
+  if (type === 'categorical') return null;
   const v = parseFloat(m.value);
   return isFinite(v) ? v : null;
 }
+// A ranked-scale (ordinal) or text (categorical) parameter's trend, as the
+// app's Stability view draws it (FormLab 13b): one point per test date × run
+// condition — an ordinal date is the MEDIAN rank of its readings (rank =
+// 1-based position on the reading's own scale), a text date its value (or
+// "mixed: a / b") — failing when any reading fails; one series per condition.
+function _mcpGradedStability(entity, entityType, args, graded) {
+  const nOrd = graded.filter(r => r.type === 'ordinal').length;
+  const kind = nOrd >= graded.length - nOrd ? 'ordinal' : 'categorical';
+  const rows = graded.filter(r => r.type === kind);
+  const scale = kind === 'ordinal' ? ((rows.find(r => r.scale) || {}).scale || null) : null;
+  const split = args.by_condition !== false;
+  const byKey = new Map();
+  rows.forEach(r => { const k = r.day + '\u0000' + (split ? r.cond : ''); if (!byKey.has(k)) byKey.set(k, []); byKey.get(k).push(r); });
+  const pts = [...byKey.values()].map(g => {
+    let label, rank = null;
+    if (kind === 'ordinal') {
+      const rs = g.map(r => r.rank).filter(v => v != null).sort((a, b) => a - b);
+      rank = rs.length ? rs[Math.floor((rs.length - 1) / 2)] : null;
+      label = rank != null && scale ? scale[rank - 1] : g[0].label;
+    } else {
+      const vals = [...new Set(g.map(r => r.label))];
+      label = vals.length === 1 ? vals[0] : 'mixed: ' + vals.join(' / ');
+    }
+    return { date: g[0].day, condition: split ? (g[0].cond || null) : null, label, ...(kind === 'ordinal' ? { rank } : {}),
+      readings: g.length, values: g.map(r => r.label), reports: [...new Set(g.map(r => r.report))],
+      pf: g.some(r => r.pf === 'fail') ? 'fail' : g.some(r => r.pf === 'pass') ? 'pass' : null };
+  }).sort((a, b) => a.date.localeCompare(b.date) || String(a.condition).localeCompare(String(b.condition)));
+  const sp = (rows.find(r => r.spec) || {}).spec || null;
+  const floorLabel = sp ? (sp.minValue != null ? sp.minValue : (sp.minRank != null && scale ? scale[sp.minRank] : null)) : null;
+  const spec = sp ? { ...(floorLabel != null ? { atLeast: floorLabel, atLeastRank: scale ? scale.indexOf(floorLabel) + 1 : null } : {}),
+    ...(sp.requiredValue != null ? { required: sp.requiredValue } : {}) } : null;
+  const byCond = new Map();
+  pts.forEach(p => { const k = p.condition || ''; if (!byCond.has(k)) byCond.set(k, []); byCond.get(k).push(p); });
+  const series = [...byCond.keys()].sort().map(k => {
+    const ps = byCond.get(k), first = ps[0], last = ps[ps.length - 1];
+    const firstFail = ps.find(p => p.pf === 'fail');
+    const out = { condition: k || null, points: ps, latest: { date: last.date, label: last.label, pf: last.pf },
+      firstFail: firstFail ? { date: firstFail.date, label: firstFail.label } : null, inSpecNow: last.pf == null ? null : last.pf === 'pass' };
+    if (kind === 'ordinal' && first.rank != null && last.rank != null) out.scaleShift = { from: first.label, to: last.label, steps: last.rank - first.rank };
+    return out;
+  });
+  return {
+    entity: { type: entityType, uid: entity.uid, name: entity.name || entity.uid },
+    parameter: args.parameter, kind, ...(scale ? { scale } : {}), spec, byCondition: split, pointCount: pts.length, series,
+    note: kind === 'ordinal'
+      ? 'A ranked scale (ordinal) has no number, so there is no regression, control chart or shelf-life projection: each point is one test date per condition, its value the MEDIAN rank of that date\'s readings (rank = position on `scale`, 1-based; higher = later on the scale). pf "fail" when any reading that date failed. scaleShift.steps is the rank change first → latest (negative = moved down the scale). Narrate firstFail / latest; do not average ranks into a number.'
+      : 'A text (categorical) result has no number: each point is one test date per condition with its value (or "mixed: a / b" when readings differ) and pass/fail against `spec.required`; pf "fail" when any reading failed. Narrate firstFail / latest.',
+  };
+}
 function _mcpCondSig(m) {
   const c = m && m.conditions;
   if (!c || typeof c !== 'object') return '';
@@ -1127,7 +1204,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. 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.',
+    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. A ranked-scale (ordinal, e.g. pencil hardness) or text (e.g. appearance) parameter returns kind "ordinal" / "categorical" instead: per-condition points with the label (median rank for an ordinal), pass/fail, firstFail, latest and scaleShift — the app\'s step / pass-fail-strip trend, with no regression. Use these figures directly; do not re-derive the regression.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1153,6 +1230,8 @@ const get_stability = {
     const paramLc = (args.parameter || '').trim().toLowerCase();
     if (!paramLc) return { error: 'parameter is required.' };
     const points = [];
+    const skipped = { ordinal: 0, categorical: 0 };
+    const graded = [];   // ordinal / text readings, for the step / strip trend (13b)
     let specMin = null, specMax = null, unit = '';
     // Each reading keeps the spec it was judged by (reading → panel row →
     // method). Mirrors the app: one band only when they all agree; 2+ distinct
@@ -1165,11 +1244,22 @@ const get_stability = {
       if (!Number.isFinite(date.getTime())) return;
       (t.measurements || []).forEach(m => {
         if ((m.parameter || '').trim().toLowerCase() !== paramLc) return;
-        let value = parseFloat(m.value);
-        if (!Number.isFinite(value) && Array.isArray(m.points) && m.points.length) {
-          const last = m.points[m.points.length - 1]; value = parseFloat(last && (last.value ?? last.y));   // time-series → final
+        // As the app's Stability chart (13a): a curve → its final value (not
+        // "12 points" → 12), and ordinal / text readings left out and counted.
+        const _ty = _mcpMeasType(m);
+        if (_ty === 'ordinal' || _ty === 'categorical') {
+          skipped[_ty]++;
+          const label = String(m.value == null ? '' : m.value).trim();
+          if (label) {
+            const rs0 = _resolveSpec(m, t.templateId);
+            graded.push({ day: dStr, type: _ty, label, rank: _mcpRepNumber(m, { ordinal: 'rank' }), scale: Array.isArray(m.scale) ? m.scale : null,
+              spec: rs0.spec || null, pf: rs0.spec ? _evalPassFail(m, t.templateId) : null, report: t.uid || t.id,
+              cond: (m.conditions && Object.keys(m.conditions).length) ? Object.entries(m.conditions).map(([k, v]) => `${k} ${v}`).join(' · ') : '' });
+          }
+          return;
         }
-        if (!Number.isFinite(value)) return;
+        const value = _mcpRepNumber(m);
+        if (value == null) return;
         if (m.unit && !unit) unit = m.unit;
         const rs = _resolveSpec(m, t.templateId), ac = rs.spec;
         const sp = (ac && (Number.isFinite(ac.min) || Number.isFinite(ac.max))) ? { min: Number.isFinite(ac.min) ? ac.min : null, max: Number.isFinite(ac.max) ? ac.max : null } : null;
@@ -1208,6 +1298,7 @@ const get_stability = {
       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 && graded.length) return _mcpGradedStability(entity, entityType, args, graded);
     if (!points.length) return { error: `No dated "${args.parameter}" measurements on ${entity.uid || entity.id}.` };
 
     const spec = { min: specMin, max: specMax };
@@ -1275,14 +1366,14 @@ const get_stability = {
 
     return {
       entity: { type: entityType, uid: entity.uid, name: entity.name || entity.uid },
-      parameter: args.parameter, unit, spec, ...(specVaries ? { specVaries, specNote: 'Readings were judged against different specs (different panels): no single band, no shelf-life projection; each reading keeps its own pass/fail.' } : {}), pointCount: points.length, byCondition: split, series,
+      parameter: args.parameter, unit, spec, ...((skipped.ordinal || skipped.categorical) ? { skipped, skippedNote: 'Ordinal (ranked scale) and text readings have no number to trend and are left out, as in the app.' } : {}), ...(specVaries ? { specVaries, specNote: 'Readings were judged against different specs (different panels): no single band, no shelf-life projection; each reading keeps its own pass/fail.' } : {}), pointCount: points.length, byCondition: split, series,
       targetShelfLife: target ? { months: target.months, source: target.source } : null,
       note: 'shelfLife.fromT0Months / ci95FromT0Months are the projected shelf life counted from the first test (T0): point estimate and the conservative (ICH Q1E) 95%-bound crossing. remainingMonths / ci95Months are the same, counted from the last test. verdict compares against targetShelfLife: "short" = the trend crosses spec before the target, "marginal" = the trend clears it but the 95% bound does not, "meets" = both clear it; null = no target set (then concern is by time left: medium <3 mo or overdue, else info). A projection never reaches \"high\": high is reserved for a MEASURED out-of-spec value (spec.latestInSpec=false). short/overdue → medium, marginal/meets → info. overdue=true means projectedCrossDate is already past today (time left runs from the last test), so the sample is probably out of spec now — recommend a re-test. reportable=false means the app shows no projection (R² < 0.3, crossing already past, or beyond 5 years). Numbers are computed here — narrate them, do not recompute.',
     };
   },
 };
 
-export { _evalPassFail, _resolveSpec, _shelfLife, _shelfLifeAssess, _mcpCondTags, _mcpArmNames, _mcpCondDefaultScore };
+export { _mcpRepNumber, _mcpMeasType, _evalPassFail, _resolveSpec, _shelfLife, _shelfLifeAssess, _mcpCondTags, _mcpArmNames, _mcpCondDefaultScore };
 export const tools = {
   list_test_results,
   get_test_result,

package/tools/designspace.js

@@ -27,6 +27,7 @@
 // ============================================================
 
 import { getStore, resolveById, flattenComposition } from '../data.js';
+import { _mcpRepNumber } from './analytics.js';
 
 // ---- composition helper -----------------------------------------------------
 // Ingredient wt-% map for one formula, mirroring the app's _asmIngredientMap:
@@ -344,12 +345,20 @@ function _roleCandidates(forms, roleMaps) {
   });
   return out.sort((a, b) => b.score - a.score);
 }
-// A formula's value for a measured parameter: the mean of every numeric
-// reading of it across the formula's samples (the app's _asmFormulaValueForCol).
+// A formula's value for a measured parameter, as the app's
+// _asmFormulaValueForCol (13a): readings of the primary run condition (the one
+// with the most readings), each as the DOE Matrix reads it (a curve's final
+// value, a distribution's D50, an ordinal's rank), then their mean.
 function _paramValue(f, param, db) {
   const sids = new Set((db.samples || []).filter(s => s.formulationId === f.id).map(s => s.id));
-  const vals = [];
-  (db.testResults || []).forEach(t => { if (!sids.has(t.sampleId)) return; (t.measurements || []).forEach(m => { if (m.parameter === param) { const v = parseFloat(m.value); if (!isNaN(v)) vals.push(v); } }); });
+  const ms = [];
+  (db.testResults || []).forEach(t => { if (!sids.has(t.sampleId)) return; (t.measurements || []).forEach(m => { if (m.parameter === param) ms.push(m); }); });
+  const sig = (m) => { const c = m && m.conditions; return c && typeof c === 'object' ? Object.keys(c).filter(k => c[k] != null && c[k] !== '').sort().map(k => k + '=' + c[k]).join('; ') : ''; };
+  const byCond = new Map();
+  ms.forEach(m => { if (_mcpRepNumber(m) == null) return; const k = sig(m); byCond.set(k, (byCond.get(k) || 0) + 1); });
+  const primary = [...byCond.entries()].sort((a, b) => b[1] - a[1])[0];
+  const pool = primary ? ms.filter(m => sig(m) === primary[0]) : ms;
+  const vals = pool.map(m => _mcpRepNumber(m, { ordinal: 'rank' })).filter(v => v != null);
   return vals.length ? vals.reduce((a, b) => a + b, 0) / vals.length : null;
 }
 function _spearman(xs, ys) {