formlab-mcp 0.6.41 → 0.6.43

package/README.md

@@ -46,9 +46,9 @@ 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. 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 |
+| `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.41",
+  "version": "0.6.43",
   "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.41",
+  "version": "0.6.43",
   "websiteUrl": "https://formvix.com/mcp",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.6.41",
+      "version": "0.6.43",
       "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. 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, on a tie the one declared as the default on the Test Method / Test Panel); they are different responses, never averaged together. 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, on a tie the one declared as the default on the Test Method / Test Panel); they are different responses, never averaged together. Parameter columns come in the same order as the app: grouped by measurement type (numbers, curves, distributions, ranked scales, text) and in the test panel order within a group. Returns CSV when format=csv (default) for compact LLM consumption, or structured JSON when format=json.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -340,8 +340,18 @@ const get_doe_matrix = {
     const armNames = _mcpArmNames(rows.flatMap(r => r.measurements
       .filter(m => m && m.parameter && parameters.has(m.parameter))
       .map(m => ({ parameter: m.parameter, m }))));
+    // Parameter columns in the app's order (13h): grouped by measurement type
+    // (numbers, curves, distributions, ranked scales, text), the test panel's
+    // order within a group — the same order as compare_test_results.
+    const testOf = new Map();
+    (db.testResults || []).forEach(t => (t.measurements || []).forEach(x => testOf.set(x, t)));
+    const ordered = _mcpParamGroupsOf(rows.flatMap(r => r.measurements.filter(m => m && m.parameter && parameters.has(m.parameter)).map(m => ({ m, t: testOf.get(m) || null }))), 'method', db)
+      .flatMap(g => g.parameters);
+    const byTrim = new Map([...parameters].map(k => [String(k).trim(), k]));
+    const paramOrder = ordered.map(p => byTrim.get(p)).filter(k => k != null);
+    [...parameters].forEach(k => { if (!paramOrder.includes(k)) paramOrder.push(k); });
     const paramCols = [];
-    [...parameters].forEach(p => {
+    paramOrder.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 }));
@@ -592,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 = [];
@@ -603,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);
@@ -612,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 };
   });
 }
@@ -792,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: {
@@ -823,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 ?? '');
@@ -885,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,
       });
@@ -1394,15 +1445,21 @@ const _MCP_PARAM_GROUPS = [
 ];
 const _mcpCmp = (a, b) => String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: 'base' }) || (a < b ? -1 : a > b ? 1 : 0);
 function _mcpParamGroups(items, sort, db) {
+  const pairs = [];
+  (items || []).forEach(it => (it.tests || []).forEach(t => (t.measurements || []).forEach(m => pairs.push({ m, t }))));
+  return _mcpParamGroupsOf(pairs, sort, db);
+}
+// From [{ m, t }] pairs (t may be null) — get_doe_matrix holds flattened measurements (13h).
+function _mcpParamGroupsOf(pairs, sort, db) {
   const sortAz = sort === 'az';
   const rank = new Map(_MCP_PARAM_GROUPS.map(([t], i) => [t, i]));
   const best = new Map(), panels = new Map(), onPanel = new Map();
-  (items || []).forEach(it => (it.tests || []).forEach(t => (t.measurements || []).forEach(m => {
+  (pairs || []).forEach(({ m, t }) => {
     const p = String((m && m.parameter) || '').trim();
     if (!p) return;
     const k = rank.get(_mcpMeasType(m)) ?? 0;
     if (!best.has(p) || k < best.get(p)) best.set(p, k);
-    if (sortAz || !t.templateId) return;
+    if (sortAz || !t || !t.templateId) return;
     if (!panels.has(t.templateId)) panels.set(t.templateId, (db.templates || []).find(x => x && x.id === t.templateId) || null);
     const panel = panels.get(t.templateId);
     const params = (panel && panel.parameters) || [];
@@ -1411,7 +1468,7 @@ function _mcpParamGroups(items, sort, db) {
     const at = [String(panel.name || ''), i];
     const cur = onPanel.get(p);
     if (!cur || _mcpCmp(at[0], cur[0]) < 0 || (at[0] === cur[0] && i < cur[1])) onPanel.set(p, at);
-  })));
+  });
   const byMethod = (a, b) => {
     const x = onPanel.get(a), y = onPanel.get(b);
     if (x && y) return _mcpCmp(x[0], y[0]) || (x[1] - y[1]) || _mcpCmp(a, b);