formlab-mcp 0.6.46 → 0.6.48

package/README.md

@@ -44,8 +44,8 @@ Ask Claude (or another MCP client) things like:
 | `get_batch` | Full record + actual composition, measured/derived **actual volume** (mass ÷ density, never a sum of per-ingredient volumes) and **actual mass** (yield, else summed as-prepared inputs — mL rows through that ingredient's density — else measured volume × density), **estimatedVolume** (mass ÷ the formula's finished density when no actual exists, flagged `estimate: true`), **plannedMass** for volume-target batches (target × finished density) and **formulaFinishedDensity**, the **process** method + any **process-factor values** (DOE inputs), samples + blend lineage, and — as a finished-goods lot — its storage **`location`** + finished-goods **`stockLedger`** (shipments out + adjustments; `shippedQty` total) |
 | `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 (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 |
+| `list_test_results` | Filtered list of test reports (by sample, parameter, **measured-value range** (`value_min`/`value_max` — a curve at its final point, a distribution at its spec's statistic or D50), **grade** (`min_grade`/`max_grade` on a ranked scale), **text value** (`value_equals`), **run condition** (`condition`), 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 distribution also its `bins` and, when its spec names a statistic, `judged` at it); a ranked grade carries its `scale` and `rank`; 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. 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, in the same order (grouped by measurement type, the test panel's order within a group), 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; one column per **run condition** when a parameter was measured under two or more — same rollup as the app's Test Analytics → Coverage. A ranked scale shows its median grade (with its `rank`) when several readings share the date, a text result its most frequent value, a distribution with no D50 its bins; columns in the app's order (type groups, the test panel's order) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.46",
+  "version": "0.6.48",
   "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.46",
+  "version": "0.6.48",
   "websiteUrl": "https://formvix.com/mcp",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.6.46",
+      "version": "0.6.48",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tools/analytics.js

@@ -84,7 +84,9 @@ function _mcpTsAggregate(points) {
 
 function _trimMeasurement(m, t, db) {
   const ins = _resolveInstrument(m, t, db);
-  const type = m.type || 'scalar';
+  // The app's type rule (13s): a legacy valueType 'Categorical' row is text,
+  // not a scalar.
+  const type = _mcpMeasType(m);
   // Reduce a complex type to the single representative every analysis surface
   // uses (time_series → final point, distribution → D50), and — for a series —
   // expose per-timestamp aggregation so an agent can see POINT replicates
@@ -101,6 +103,16 @@ function _trimMeasurement(m, t, db) {
   } else if (type === 'distribution' && Array.isArray(m.bins) && m.bins.length) {
     const d50 = m.bins.find(b => String(b.label || '').toUpperCase().replace(/\s/g, '') === 'D50');
     complex.representative = d50 ? { value: _round(parseFloat(d50.value), 6), basis: 'D50' } : null;
+    complex.bins = m.bins.map(b => ({ label: b.label, value: b.value }));
+    // The statistic its spec names is the one it is judged on ("D90 <=30").
+    const sp = _resolveSpec(m, t && t.templateId, db).spec;
+    if (sp && sp.stat) { const v = _mcpRepNumber(m, { dist: String(sp.stat) }); complex.judged = { value: v != null ? _round(v, 6) : null, basis: String(sp.stat) }; }
+  } else if (type === 'ordinal' && Array.isArray(m.scale) && m.scale.length) {
+    // A grade's order (13s): the scale and its place on it, so a floor like
+    // "at least HB" can be reasoned about.
+    complex.scale = m.scale.slice();
+    const r = _mcpRepNumber(m, { ordinal: 'rank' });
+    if (r != null) complex.rank = r;
   }
   return {
     parameter: m.parameter || '',
@@ -127,7 +139,7 @@ function _trimMeasurement(m, t, db) {
 const list_test_results = {
   definition: {
     name: 'list_test_results',
-    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.',
+    description: 'List test result reports, optionally filtered by sample, parameter, measured-value range, grade, text value, run condition, 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). The number a range filter reads: a scalar as recorded, a curve at its final point, a distribution at the statistic its spec names (D90) or else D50; a ranked scale or text result has no number — use min_grade / max_grade (positions on the reading\'s own scale, e.g. parameter="Pencil hardness", min_grade="HB") or value_equals (a text result, case-insensitive). condition narrows to readings under a run condition (substring of e.g. "Storage 40 °C"; "none" = readings with no condition). 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: {
@@ -135,6 +147,10 @@ const list_test_results = {
         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.' },
+        min_grade: { type: 'string', description: 'A ranked scale: only readings at or above this grade on the reading\'s own scale (e.g. "HB").' },
+        max_grade: { type: 'string', description: 'A ranked scale: only readings at or below this grade.' },
+        value_equals: { type: 'string', description: 'A text (or ranked) result equal to this value, case-insensitive (e.g. "pass", "slight haze").' },
+        condition: { type: 'string', description: 'Only readings under a run condition whose label contains this (e.g. "40 °C"); "none" = readings with no run condition.' },
         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).' },
@@ -159,16 +175,32 @@ const list_test_results = {
       if (args.until_date && (t.testDate || '') > args.until_date) return false;
       if (args.lab && !norm(t.lab).includes(norm(args.lab))) return false;
       const hasRange = args.value_min != null || args.value_max != null;
-      if (args.parameter || hasRange) {
+      const hasGrade = !!(args.min_grade || args.max_grade);
+      if (args.parameter || hasRange || hasGrade || args.value_equals || args.condition) {
         const pn = norm(args.parameter);
         const found = (t.measurements || []).some(m => {
           if (args.parameter && !norm(m.parameter).includes(pn)) return false;
+          if (args.condition) {
+            const lbl = norm(_mcpCondLabel(m));
+            if (norm(args.condition) === 'none' ? lbl !== '' : !lbl.includes(norm(args.condition))) return false;
+          }
           if (hasRange) {
-            const v = _mcpRepNumber(m);   // a curve's final value, not its point count (12v)
+            // The value it is judged on (13s): a distribution at its spec's statistic.
+            const sp = _mcpMeasType(m) === 'distribution' ? (_resolveSpec(m, t.templateId, db).spec || null) : null;
+            const v = sp && sp.stat ? _mcpRepNumber(m, { dist: String(sp.stat) }) : _mcpRepNumber(m);   // a curve's final value, not its point count (12v)
             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;
           }
+          if (hasGrade) {
+            if (_mcpMeasType(m) !== 'ordinal' || !Array.isArray(m.scale)) return false;
+            const up = m.scale.map(g => String(g).trim().toUpperCase());
+            const r = up.indexOf(String(m.value == null ? '' : m.value).trim().toUpperCase());
+            if (r < 0) return false;
+            if (args.min_grade) { const lo = up.indexOf(String(args.min_grade).trim().toUpperCase()); if (lo < 0 || r < lo) return false; }
+            if (args.max_grade) { const hi = up.indexOf(String(args.max_grade).trim().toUpperCase()); if (hi < 0 || r > hi) return false; }
+          }
+          if (args.value_equals && norm(String(m.value == null ? '' : m.value).trim()) !== norm(String(args.value_equals).trim())) return false;
           return true;
         });
         if (!found) return false;
@@ -359,13 +391,23 @@ const get_doe_matrix = {
 
     // 4) Aggregate measurements per column per row (mean of numeric scalar
     //    values), reading only the column's own run condition when split.
+    const testOfM = new Map();
+    (db.testResults || []).forEach(t => (t.measurements || []).forEach(x => testOfM.set(x, t)));
     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;
       // The app's DOE Matrix numbers (12v): a curve's final value, a
-      // distribution's D50, an ordinal's 1-based rank; text → its first reading.
+      // distribution's D50, a grade's place on its scale. 13r: a ranked scale
+      // is its LOWER-median grade (never an averaged rank); text its most
+      // frequent value, a tie to a failing one (it took the first reading); a
+      // distribution with no D50 its bins (it read "8 bins").
       const nums = ms.map(m => _mcpRepNumber(m, { ordinal: 'rank' })).filter(v => v != null);
-      if (!nums.length) return ms[0].value ?? null;
+      if (!nums.length) {
+        const rows = ms.map(m => { const t = testOfM.get(m); return { m, type: _mcpMeasType(m), value: m.value, numeric: null, rank: null, pf: _evalPassFail(m, t && t.templateId) }; });
+        if (rows.every(x => x.type === 'categorical')) return _mcpGradedPick(rows).value ?? null;
+        return _mcpCellValue(rows[0]);
+      }
+      if (ms.every(m => _mcpMeasType(m) === 'ordinal')) { const so = nums.slice().sort((a, b) => a - b); return so[Math.floor((so.length - 1) / 2)]; }
       const mean = nums.reduce((s, v) => s + v, 0) / nums.length;
       return +mean.toFixed(4);
     };
@@ -462,7 +504,7 @@ function _mcpRepNumber(m, opts) {
 // app's Stability view draws it (FormLab 12w): 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.
+// the most frequent value, a tie to a failing one) — 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';
@@ -478,8 +520,11 @@ function _mcpGradedStability(entity, entityType, args, graded) {
       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(' / ');
+      // The most frequent value, a tie to a failing one (13r) — "mixed: a / b" said
+      // nothing about which reading counts. The chip's tooltip lists them all.
+      const k = r => String(r.label).toLowerCase(); const cnt = new Map(); g.forEach(r => cnt.set(k(r), (cnt.get(k(r)) || 0) + 1));
+      const top = Math.max(...cnt.values()); const tied = g.filter(r => cnt.get(k(r)) === top);
+      label = (tied.find(r => r.pf === 'fail') || tied[0]).label;
     }
     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))],
@@ -504,7 +549,7 @@ function _mcpGradedStability(entity, entityType, args, graded) {
     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.',
+      : 'A text (categorical) result has no number: each point is one test date per condition with its value (several readings that differ → the most frequent, a tie to a failing one; `values` lists them) and pass/fail against `spec.required`; pf "fail" when any reading failed. Narrate firstFail / latest.',
   };
 }
 function _mcpCondSig(m) {
@@ -812,7 +857,8 @@ function _evalPassFail(m, templateId, db) {
   if (type === 'ordinal') {
     if (!raw) return 'untested';
     const scale = Array.isArray(m.scale) ? m.scale : [];
-    const idx = scale.indexOf(raw);
+    // Case-insensitive, as flMeasNum places a grade (13r): "hb" was judged untested but plotted at HB.
+    const idx = scale.map(g => String(g).trim().toUpperCase()).indexOf(raw.toUpperCase());
     if (idx < 0) return 'untested';
     const minRank = _ordinalMinRank(crit, scale);
     if (minRank == null) return 'no-criteria';
@@ -1511,8 +1557,39 @@ function _mcpCompareCell(item, parameter, agg, db) {
     if (!arms.has(sig)) arms.set(sig, { sig, m, t, rows: [] });
     arms.get(sig).rows.push({ m, t, date: _tcDate(t), value: v, pf: _evalPassFail(m, t.templateId, db) });
   });
-  // Nothing numeric (a ranked scale, a text result, a distribution with no D50):
-  // the latest reading, as typed.
+  // A ranked scale or a text result (13r, as the app's Compare): per run
+  // condition, no condition first, the latest test date — several readings on
+  // it → the lower-median grade / the most frequent text (a tie to a failing
+  // one), failing if any reading fails; two or more conditions → arms.
+  if (!arms.size && (type === 'ordinal' || type === 'categorical')) {
+    const g = new Map();
+    hits.forEach(({ m, t }) => {
+      const label = String(m.value == null ? '' : m.value).trim(); if (!label) return;
+      const sig = _mcpCondSig(m), day = String(t.testDate || '').slice(0, 10);
+      if (!g.has(sig)) g.set(sig, { sig, m, days: new Map() });
+      const a = g.get(sig); if (!a.days.has(day)) a.days.set(day, []);
+      a.days.get(day).push({ type: _mcpMeasType(m), value: label, rank: _mcpRepNumber(m, { ordinal: 'rank' }), pf: _evalPassFail(m, t.templateId, db), m });
+    });
+    const gl = [...g.values()].sort((x, y) => ((x.sig ? 1 : 0) - (y.sig ? 1 : 0)) || (y.days.size - x.days.size) || x.sig.localeCompare(y.sig));
+    if (gl.length) {
+      const cellOf = (a) => {
+        const day = [...a.days.keys()].sort().pop(); const rs = a.days.get(day); const p = _mcpGradedPick(rs);
+        const pf = rs.some(r => r.pf === 'fail') ? 'fail' : rs.some(r => r.pf === 'pass') ? 'pass' : rs[0].pf;
+        const c = { type, value: p.value, pf, date: day, n: a.days.size, readings: [...a.days.values()].reduce((x, r) => x + r.length, 0),
+          ...(rs.length > 1 ? { readingsOnDate: rs.map(r => r.value), basis: type === 'ordinal' ? 'middle grade of the date\'s readings' : 'most frequent of the date\'s readings' } : {}) };
+        if (type === 'ordinal' && p.rank != null && Array.isArray(p.m.scale)) { c.rank = p.rank; c.scaleLength = p.m.scale.length; }
+        return c;
+      };
+      const cells = gl.map(cellOf);
+      if (agg !== 'latest' && hits.length > 1) cells.forEach(c => { c.note = 'not a number — the latest test date is shown'; });
+      if (gl.length === 1) return { ...cells[0], ...(gl[0].sig ? { condition: _mcpCondLabel(gl[0].m) } : {}) };
+      const tags = _mcpCondTags(gl.map(a => a.sig ? _mcpCondLabel(a.m) : ''));
+      return { ...cells[0], splitByCondition: true,
+        arms: gl.map((a, i) => ({ condition: a.sig ? _mcpCondLabel(a.m) : null, tag: tags[i], ...cells[i] })),
+        note: 'measured under more than one run condition: one arm per condition, never mixed; the top-level value is the first arm (no run condition when there is one)' };
+    }
+  }
+  // Nothing numeric (a distribution with no D50): the latest reading.
   if (!arms.size) {
     const { m, t } = hits[hits.length - 1];
     const out = { type, value: m.value ?? null, unit: m.unit || '', pf: _evalPassFail(m, t.templateId, db), date: t.testDate || '', readings: hits.length };