formlab-mcp 0.6.42 → 0.6.44

package/README.md

@@ -48,7 +48,7 @@ Ask Claude (or another MCP client) things like:
 | `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. 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 |
+| `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) |
 | `compare_test_results` | **Test results** side by side across 2+ formulas, batches, samples or reports — the app's Compare Results table. Parameters grouped by measurement type (Numbers, Curves, Distributions, Ranked scales, Text results) and, within a group, in the test panel's order (`order: method`, default) or `az`. One cell per item × parameter: `aggregation` `latest` (default; one value per test date, replicates averaged ± sd), `mean` (± sd between dates), `median` (min–max) or `trend` (change from the first date). Curves compare at their final point, distributions at D50; ranked scales and text show the latest reading (with its rank); a parameter measured under 2+ run conditions is split into `arms`, never averaged. `differs` flags a >5% spread across items, as the app highlights |
 | `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 |

package/package.json

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

package/tools/analytics.js

@@ -602,6 +602,32 @@ function _mcpArmNames(items) {
   return out;
 }
 
+// Ranked scales and text results (13i, mirrors the app's _taGradedPick): the
+// reading that stands for several — a ranked scale's LOWER median by position
+// on the scale (never an average of ranks), a text result's most frequent
+// value with a tie going to a failing one. It used to be the first one read.
+const _mcpGraded = (r) => !!r && (r.type === 'ordinal' || r.type === 'categorical');
+function _mcpGradedPick(list) {
+  if (list[0].type === 'ordinal') {
+    const ranked = list.filter(r => r.rank != null).sort((a, b) => a.rank - b.rank);
+    return ranked.length ? ranked[Math.floor((ranked.length - 1) / 2)] : list[list.length - 1];
+  }
+  const key = (r) => String(r.value == null ? '' : r.value).trim().toLowerCase();
+  const cnt = new Map(); list.forEach(r => cnt.set(key(r), (cnt.get(key(r)) || 0) + 1));
+  const top = Math.max(...cnt.values());
+  const tied = list.filter(r => cnt.get(key(r)) === top);
+  return tied.find(r => r.pf === 'fail') || tied[0];
+}
+// A cell's value when it has no number: a distribution with no D50 shows its
+// bins (it showed "3 bins", the count); otherwise the reading as recorded.
+function _mcpCellValue(r) {
+  if (r.numeric != null) return r.numeric;
+  const m = r.m;
+  if (r.type === 'distribution' && m && Array.isArray(m.bins) && m.bins.length)
+    return m.bins.map(b => `${b.label} ${b.value}`).join(' · ');
+  return r.value;
+}
+
 function _mcpFlattenReadings(tests, indexes, paramFilter) {
   const norm = (s) => String(s || '').toLowerCase();
   const groups = new Map(); const order = [];
@@ -613,7 +639,9 @@ function _mcpFlattenReadings(tests, indexes, paramFilter) {
       const parameter = String(m.parameter || '').trim();
       if (!parameter) continue;
       if (paramFilter && !norm(parameter).includes(norm(paramFilter))) continue;
-      const row = { test: t, sample: samp, formulation, parameter, numeric: _mcpRepNumber(m), value: m.value, unit: m.unit || '', pf: _evalPassFail(m, t.templateId), m };
+      const type = _mcpMeasType(m);
+      const row = { test: t, sample: samp, formulation, parameter, numeric: _mcpRepNumber(m), value: m.value, unit: m.unit || '', pf: _evalPassFail(m, t.templateId), m,
+        type, rank: type === 'ordinal' ? _mcpRepNumber(m, { ordinal: 'rank' }) : null };
       const key = (t.id || t.uid) + '|' + parameter + '|' + _mcpCondSig(m);
       if (!groups.has(key)) { groups.set(key, []); order.push(key); }
       groups.get(key).push(row);
@@ -622,9 +650,10 @@ function _mcpFlattenReadings(tests, indexes, paramFilter) {
   return order.map(k => {
     const g = groups.get(k);
     if (g.length === 1) return g[0];
+    const pf = g.some(r => r.pf === 'fail') ? 'fail' : g.some(r => r.pf === 'pass') ? 'pass' : g[0].pf;
+    if (_mcpGraded(g[0])) return { ..._mcpGradedPick(g), pf, replicates: g.length };
     const nums = g.map(r => r.numeric).filter(v => v != null && isFinite(v));
     const mean = nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : null;
-    const pf = g.some(r => r.pf === 'fail') ? 'fail' : g.some(r => r.pf === 'pass') ? 'pass' : g[0].pf;
     return { ...g[0], numeric: mean, value: mean != null ? mean : g[0].value, pf, replicates: g.length };
   });
 }
@@ -802,7 +831,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 — 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".',
+    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). A ranked scale shows its median grade when several readings share the date (with its rank on the scale), a text result its most frequent value, a distribution with no D50 its bins. Columns come in the same order as the app: grouped by measurement type, the test panel order within a group. Empty = never tested. Use for "what\'s untested", "what\'s the current value" and "what\'s been measured many times".',
     inputSchema: {
       type: 'object',
       properties: {
@@ -833,14 +862,24 @@ const get_coverage_matrix = {
     const rows = _mcpCoverageRows(flat, grain, indexes);
     const paramSet = new Set();
     rows.forEach(r => r.cells.forEach((_, p) => paramSet.add(p)));
-    const paramCols = [...paramSet].sort();
+    // The app's column order (13i): grouped by measurement type, the test
+    // panel's order within a group, each run condition right after its
+    // parameter. It was A–Z, case-sensitive (pH after Viscosity).
+    const armOf = new Map();
+    _mcpArmNames(flat).forEach((names, param) => names.forEach(nm => { if (nm !== param) armOf.set(nm, param); }));
+    const paramCols = [];
+    _mcpParamGroupsOf(flat.map(r => ({ m: r.m, t: r.test })), 'method', db).flatMap(g => g.parameters).forEach(b => {
+      if (paramSet.has(b)) paramCols.push(b);
+      [...paramSet].filter(p => armOf.get(p) === b).sort((x, y) => x.localeCompare(y)).forEach(p => paramCols.push(p));
+    });
+    [...paramSet].forEach(p => { if (!paramCols.includes(p)) paramCols.push(p); });
     const sorted = [...rows.values()].sort((a, b) => String(a.label).localeCompare(String(b.label)));
     const grainLabel = grain === 'formulation' ? 'Formulation' : grain === 'batch' ? 'Batch' : 'Sample';
     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); 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()) })),
+        rows: sorted.map(r => ({ [grain]: r.label, id: r.uid, cells: Object.fromEntries(paramCols.filter(p => r.cells.has(p)).map(p => [p, r.cells.get(p)])) })),
       };
     }
     const esc = (v) => /[",\n\r]/.test(String(v ?? '')) ? '"' + String(v).replace(/"/g, '""') + '"' : String(v ?? '');
@@ -895,8 +934,10 @@ function _mcpCoverageRows(flat, grain, indexes) {
       // 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;
+      const pick = list.length === 1 ? list[0] : _mcpGraded(list[0]) ? _mcpGradedPick(list) : null;
       row.cells.set(param, {
-        value: tidy(list.length === 1 ? (list[0].numeric != null ? list[0].numeric : list[0].value) : (mean != null ? mean : list[0].value)),
+        value: tidy(pick ? _mcpCellValue(pick) : (mean != null ? mean : _mcpCellValue(list[0]))),
+        ...(pick && pick.type === 'ordinal' && pick.rank != null ? { rank: pick.rank } : {}),
         unit: list[0].unit, pf: (pf === 'pass' || pf === 'fail') ? pf : null,
         latestDate: date || null, reportsAveraged: list.length, nReports: row.reports.get(param).size,
       });
@@ -1480,8 +1521,8 @@ function _mcpCompareCell(item, parameter, agg, db) {
     });
     return { sig: a.sig, m: a.m, t: points[points.length - 1].t, latestM: points[points.length - 1].m, points, readings: a.rows.length };
   });
-  // Primary first: the longest record, then the declared default condition, then the most recent, then by name.
-  series.sort((a, b) => (b.points.length - a.points.length)
+  // Primary first: no run condition when there is one (13n), then the longest record, the declared default condition, the most recent, then by name.
+  series.sort((a, b) => ((a.sig ? 1 : 0) - (b.sig ? 1 : 0)) || (b.points.length - a.points.length)
     || (_mcpCondDefaultScore(b.latestM, b.t, db) - _mcpCondDefaultScore(a.latestM, a.t, db))
     || (b.points[b.points.length - 1].date - a.points[a.points.length - 1].date) || _mcpCmp(a.sig, b.sig));
   const basis = type === 'time_series' ? 'final' : type === 'distribution' ? 'D50' : undefined;
@@ -1509,7 +1550,7 @@ function _mcpCompareCell(item, parameter, agg, db) {
   const tags = _mcpCondTags(series.map(s => s.sig ? _mcpCondLabel(s.m) : ''));
   return { type, ...cells[0], splitByCondition: true,
     arms: series.map((s, i) => ({ condition: s.sig ? _mcpCondLabel(s.m) : null, tag: tags[i], ...cells[i] })),
-    note: 'measured under more than one run condition: one arm per condition, never averaged; the top-level value is the first arm (the longest record)' };
+    note: 'measured under more than one run condition: one arm per condition, never averaged; the top-level value is the first arm (no run condition when there is one, else the longest record)' };
 }
 
 // The app's difference highlight (_tcKeysDiffer): numbers differ when their