formlab-mcp 0.6.40 → 0.6.42

package/README.md

@@ -16,6 +16,7 @@ Ask Claude (or another MCP client) things like:
 
 - _"Which of my formulations use silicone fluid at 5% or more?"_
 - _"Compare the composition of Formula FORM-001 and FORM-004 side by side."_
+- _"Compare the test results of Coating A and Coating B — which parameters differ, and does either fail?"_
 - _"What parameters fail most often in Q2 testing?"_
 - _"Show me the DOE matrix at sample grain for all 'Anti-aging serum' family formulas."_
 - _"What's untested? Which of my approved formulas have no measurements yet?"_
@@ -45,9 +46,10 @@ 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 |
+| `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 |
 | `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 |

package/package.json

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

package/tools/analytics.js

@@ -164,7 +164,7 @@ const list_test_results = {
         const found = (t.measurements || []).some(m => {
           if (args.parameter && !norm(m.parameter).includes(pn)) return false;
           if (hasRange) {
-            const v = _mcpRepNumber(m);   // a curve's final value, not its point count (13a)
+            const v = _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;
@@ -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 }));
@@ -352,7 +362,7 @@ 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;
-      // The app's DOE Matrix numbers (13a): a curve's final value, a
+      // 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.
       const nums = ms.map(m => _mcpRepNumber(m, { ordinal: 'rank' })).filter(v => v != null);
       if (!nums.length) return ms[0].value ?? null;
@@ -407,7 +417,7 @@ 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"
-// One number per measurement — the app's flMeasNum (js/utils.js, 13a), kept
+// One number per measurement — the app's flMeasNum (js/utils.js, 12v), 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');
@@ -449,7 +459,7 @@ function _mcpRepNumber(m, opts) {
   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
+// 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.
@@ -774,7 +784,7 @@ function _evalPassFail(m, templateId, db) {
     if (!crit.requiredValue) return 'no-criteria';
     return raw.toLowerCase() === String(crit.requiredValue).toLowerCase() ? 'pass' : 'fail';
   }
-  // As the app (13d): one representative value against the range — a curve's
+  // As the app (12y): one representative value against the range — a curve's
   // FINAL point, a distribution's statistic named by the spec (crit.stat:
   // "D90"), D50 when unnamed. It used to require every point / bin in range.
   if (type === 'time_series' || type === 'distribution') {
@@ -1232,7 +1242,7 @@ const get_stability = {
     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)
+    const graded = [];   // ordinal / text readings, for the step / strip trend (12w)
     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
@@ -1245,7 +1255,7 @@ const get_stability = {
       if (!Number.isFinite(date.getTime())) return;
       (t.measurements || []).forEach(m => {
         if ((m.parameter || '').trim().toLowerCase() !== paramLc) return;
-        // As the app's Stability chart (13a): a curve → its final value (not
+        // As the app's Stability chart (12v): 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') {
@@ -1375,8 +1385,225 @@ const get_stability = {
 };
 
 export { _mcpRepNumber, _mcpMeasType, _evalPassFail, _resolveSpec, _shelfLife, _shelfLifeAssess, _mcpCondTags, _mcpArmNames, _mcpCondDefaultScore };
+// ============================================================
+// compare_test_results — the app's Compare Results table (js/views/testing-
+// compare.js), 13g. Items are formulas, batches, samples or test reports; each
+// gathers the reports behind it (a formula: every report on its samples). The
+// parameters are grouped by measurement type — numbers, curves, distributions,
+// ranked scales, text — and, within a group, in the test panel's order
+// ('method', stable) or by name ('az'), the same rule as the app (utils.js
+// flParamGroups). One cell per item × parameter, rolled up as the app does:
+// one value per test DATE (replicates on a date averaged), a curve as its final
+// point and a distribution as its D50 (flMeasNum), a parameter measured under
+// two or more run conditions split into one arm per condition (never averaged
+// across them), a ranked scale or text result shown as its latest reading.
+// ============================================================
+const _MCP_PARAM_GROUPS = [
+  ['scalar', 'Numbers'], ['time_series', 'Curves'], ['distribution', 'Distributions'],
+  ['ordinal', 'Ranked scales'], ['categorical', 'Text results'],
+];
+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();
+  (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 || !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) || [];
+    const i = params.findIndex(x => x && ((m.parameterId && x.parameterId === m.parameterId) || String(x.parameter || x.name || '').trim() === p));
+    if (i < 0) return;
+    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);
+    if (x || y) return x ? -1 : 1;
+    return _mcpCmp(a, b);
+  };
+  const names = [...best.keys()];
+  return _MCP_PARAM_GROUPS.map(([type, label], i) => ({ type, label,
+    parameters: names.filter(p => best.get(p) === i).sort(sortAz ? _mcpCmp : byMethod) }))
+    .filter(g => g.parameters.length);
+}
+
+const _tcDate = (t) => t.testDate ? new Date(t.testDate).getTime() : (t.createdAt ? new Date(t.createdAt).getTime() : 0);
+const _tcIso = (ms) => { const d = new Date(ms); return Number.isFinite(d.getTime()) && ms ? d.toISOString().slice(0, 10) : ''; };
+
+// One item × parameter. Mirrors _tcCellRollup / _perfParamSummaries / _tcSeriesCell.
+function _mcpCompareCell(item, parameter, agg, db) {
+  const hits = [];
+  (item.tests || []).forEach(t => (t.measurements || []).forEach(m => { if (String(m.parameter || '').trim() === parameter) hits.push({ m, t }); }));
+  if (!hits.length) return null;
+  hits.sort((a, b) => _tcDate(a.t) - _tcDate(b.t));
+  const type = _mcpMeasType(hits[0].m);
+  const arms = new Map();
+  hits.forEach(({ m, t }) => {
+    const v = _mcpRepNumber(m);
+    if (v == null || !isFinite(v)) return;
+    const sig = _mcpCondSig(m);
+    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.
+  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 };
+    if (type === 'ordinal' && Array.isArray(m.scale)) { const r = _mcpRepNumber(m, { ordinal: 'rank' }); if (r != null) { out.rank = r; out.scaleLength = m.scale.length; } }
+    if (type === 'distribution' && Array.isArray(m.bins)) { out.value = null; out.bins = m.bins.map(b => ({ label: b.label, value: b.value })); out.note = 'no D50 bin, so no single value'; }
+    if (hits.length > 1 && (agg === 'mean' || agg === 'median' || agg === 'trend')) out.note = (out.note ? out.note + '; ' : '') + 'not a number — the latest reading is shown';
+    return out;
+  }
+  const series = [...arms.values()].map(a => {
+    const byDay = new Map();
+    a.rows.forEach(r => { if (!byDay.has(r.date)) byDay.set(r.date, []); byDay.get(r.date).push(r); });
+    const points = [...byDay.keys()].sort((x, y) => x - y).map(d => {
+      const g = byDay.get(d); const vals = g.map(r => r.value);
+      const mean = vals.reduce((x, y) => x + y, 0) / vals.length;
+      const sd = vals.length >= 2 ? Math.sqrt(vals.reduce((x, v) => x + (v - mean) ** 2, 0) / (vals.length - 1)) : 0;
+      const pf = g.some(r => r.pf === 'fail') ? 'fail' : g.some(r => r.pf === 'pass') ? 'pass' : g[0].pf;
+      return { date: d, value: mean, sd, pf, replicates: g.length, m: g[0].m, t: g[0].t };
+    });
+    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)
+    || (_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;
+  const one = (s) => {
+    const lat = s.points[s.points.length - 1]; const vals = s.points.map(p => p.value);
+    const typed = (lat.replicates === 1 && isFinite(+String(lat.m.value ?? '').trim()) && String(lat.m.value ?? '').trim() !== '' && type === 'scalar') ? +String(lat.m.value).trim() : _round(lat.value, 6);
+    const latest = { date: _tcIso(lat.date), value: typed, pf: lat.pf, replicates: lat.replicates, ...(lat.replicates > 1 ? { sd: _round(lat.sd, 6) } : {}) };
+    const c = { value: latest.value, unit: s.m.unit || '', ...(basis ? { basis } : {}), n: s.points.length, readings: s.readings, latest };
+    if (agg === 'mean' && vals.length > 1) {
+      const mean = vals.reduce((x, y) => x + y, 0) / vals.length;
+      c.value = _round(mean, 6); c.sd = _round(Math.sqrt(vals.reduce((x, v) => x + (v - mean) ** 2, 0) / (vals.length - 1)), 6);
+    } else if (agg === 'median' && vals.length > 1) {
+      const so = vals.slice().sort((x, y) => x - y), k = so.length;
+      c.value = _round(k % 2 ? so[(k - 1) / 2] : (so[k / 2 - 1] + so[k / 2]) / 2, 6); c.min = _round(so[0], 6); c.max = _round(so[k - 1], 6);
+    } else if (agg === 'trend') {
+      const first = vals[0], last = vals[vals.length - 1];
+      const pct = vals.length < 2 ? 0 : first !== 0 ? (last - first) / Math.abs(first) * 100 : (last === first ? 0 : null);
+      c.trend = { first: _round(first, 6), last: _round(last, 6), changePct: pct == null ? null : _round(pct, 2),
+        direction: pct == null ? (last > first ? 'up' : 'down') : Math.abs(pct) < 1 ? 'flat' : (pct > 0 ? 'up' : 'down') };
+    }
+    return c;
+  };
+  const cells = series.map(one);
+  if (series.length === 1) return { type, ...cells[0], ...(series[0].sig ? { condition: _mcpCondLabel(series[0].m) } : {}) };
+  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)' };
+}
+
+// The app's difference highlight (_tcKeysDiffer): numbers differ when their
+// spread is more than 5% of the largest magnitude; text on a case-insensitive match.
+function _mcpCellsDiffer(cells) {
+  const live = cells.filter(c => c && (c.value != null || c.trend));
+  if (live.length < 2) return false;
+  const dirs = live.map(c => (c.trend && c.trend.direction) || '');
+  if (dirs.some(d => d !== dirs[0])) return true;
+  const nums = live.map(c => (typeof c.value === 'number' ? c.value : NaN));
+  if (nums.every(Number.isFinite)) {
+    const lo = Math.min(...nums), hi = Math.max(...nums);
+    return hi !== lo && (hi - lo) / Math.max(Math.abs(lo), Math.abs(hi)) > 0.05;
+  }
+  const low = live.map(c => String(c.value ?? '').trim().toLowerCase());
+  return low.some(k => k !== low[0]);
+}
+
+const compare_test_results = {
+  definition: {
+    name: 'compare_test_results',
+    description: 'Compare TEST RESULTS side by side across 2+ formulas, batches, samples or test reports — the app\'s Compare Results table. Each item gathers the reports behind it (a formula: every report on its samples; a batch: reports on samples drawn from it). Parameters come 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 A–Z ("az"). One cell per item × parameter: aggregation "latest" (default) = the most recent test date (replicates on one date averaged, ± sd), "mean" = mean of the per-date values ± sd between dates, "median" = median with min–max, "trend" = latest with the change from the first date. A curve is compared at its final point and a distribution at its D50; a ranked scale or text result shows its latest reading (with its rank on the scale). A parameter measured under 2+ run conditions (e.g. storage 25 °C vs 40 °C) is split into arms, never averaged across conditions. `differs` flags a parameter whose values spread by more than 5% across items, as the app highlights. For composition differences use compare_formulations; for production runs, compare_batches.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mode: { type: 'string', enum: ['formulations', 'batches', 'samples', 'tests'], description: 'What the ids are. Default formulations.' },
+        ids: { type: 'array', items: { type: 'string' }, description: '2–20 ids or UIDs (FORM-…, BATCH-…, SAMP-…, TEST-…); a formula may also be given by its exact name.' },
+        aggregation: { type: 'string', enum: ['latest', 'mean', 'median', 'trend'], description: 'How each cell rolls up several test dates. Default latest. Ignored in tests mode (one report per item).' },
+        order: { type: 'string', enum: ['method', 'az'], description: 'Parameter order within each type group: the test panel\'s order (default) or A–Z.' },
+        parameter_filter: { type: 'string', description: 'Only parameters whose name contains this (case-insensitive).' },
+      },
+      required: ['ids'],
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const mode = ['formulations', 'batches', 'samples', 'tests'].includes(args.mode) ? args.mode : 'formulations';
+    const agg = mode === 'tests' ? 'latest' : (['latest', 'mean', 'median', 'trend'].includes(args.aggregation) ? args.aggregation : 'latest');
+    const order = args.order === 'az' ? 'az' : 'method';
+    if (!Array.isArray(args.ids) || args.ids.length < 2) return { error: 'Pass at least 2 ids.' };
+    if (args.ids.length > 20) return { error: 'Compare at most 20 items at once.' };
+    const coll = { formulations: 'formulations', batches: 'batches', samples: 'samples', tests: 'testResults' }[mode];
+    const lc = (s) => String(s || '').trim().toLowerCase();
+    const resolve = (id) => resolveById(coll, id) || (mode === 'formulations' ? (db.formulations || []).find(f => f && lc(f.name) === lc(id)) : null);
+    const recs = []; const missing = [];
+    args.ids.forEach(id => { const r = resolve(id); if (!r) missing.push(id); else if (!recs.includes(r)) recs.push(r); });
+    if (recs.length < 2) return { error: `Fewer than 2 of the ids resolved to ${mode}.`, missing };
+    const samplesById = new Map((db.samples || []).map(s => [s.id, s]));
+    const formOf = (s) => s && s.formulationId ? (db.formulations || []).find(f => f.id === s.formulationId) : null;
+    const pf = lc(args.parameter_filter);
+    const narrow = (t) => pf ? { ...t, measurements: (t.measurements || []).filter(m => lc(m.parameter).includes(pf)) } : t;
+    const items = recs.map(r => {
+      const tests = (mode === 'tests' ? [r] : (db.testResults || []).filter(t => {
+        const s = samplesById.get(t.sampleId);
+        return mode === 'samples' ? t.sampleId === r.id : mode === 'batches' ? !!(s && s.batchId === r.id) : !!(s && s.formulationId === r.id);
+      })).map(narrow);
+      const days = tests.map(t => t.testDate).filter(Boolean).sort();
+      const smp = mode === 'tests' ? samplesById.get(r.sampleId) : mode === 'samples' ? r : null;
+      const form = mode === 'formulations' ? r : mode === 'batches' ? (db.formulations || []).find(f => f.id === r.formulationId) : formOf(smp);
+      return { rec: r, tests, head: {
+        id: r.id, uid: r.uid || null,
+        name: mode === 'formulations' ? (r.name || '') : mode === 'tests' ? (r.reportName || r.uid || '') : (r.uid || r.id),
+        ...(mode !== 'formulations' && form ? { formula: form.uid || form.name } : {}),
+        tests: tests.length, samples: new Set(tests.map(t => t.sampleId).filter(Boolean)).size,
+        dateRange: days.length ? (days[0] === days[days.length - 1] ? days[0] : `${days[0]} … ${days[days.length - 1]}`) : null,
+      } };
+    });
+    const keyOf = (it) => it.head.uid || it.head.id;
+    const groups = _mcpParamGroups(items, order, db).map(g => ({
+      type: g.type, label: g.label,
+      parameters: g.parameters.map(p => {
+        const cells = items.map(it => _mcpCompareCell(it, p, agg, db));
+        const unit = (cells.find(c => c && c.unit) || {}).unit || '';
+        return { parameter: p, ...(unit ? { unit } : {}), differs: _mcpCellsDiffer(cells),
+          missingFrom: items.filter((_, i) => !cells[i]).map(keyOf),
+          values: Object.fromEntries(items.map((it, i) => [keyOf(it), cells[i]])) };
+      }),
+    }));
+    const paramCount = groups.reduce((n, g) => n + g.parameters.length, 0);
+    return {
+      mode, aggregation: agg, order,
+      items: items.map(it => it.head),
+      ...(missing.length ? { missing } : {}),
+      parameterCount: paramCount,
+      differingCount: groups.reduce((n, g) => n + g.parameters.filter(p => p.differs).length, 0),
+      groups,
+      note: 'values are keyed by each item\'s uid (or id). n = test dates behind a value; readings = every reading. A pass/fail (pf) is the latest date\'s verdict: a date fails when any of its readings fails.',
+    };
+  },
+};
+
 export const tools = {
   list_test_results,
+  compare_test_results,
   get_test_result,
   get_doe_matrix,
   find_failures,

package/tools/designspace.js

@@ -346,7 +346,7 @@ function _roleCandidates(forms, roleMaps) {
   return out.sort((a, b) => b.score - a.score);
 }
 // A formula's value for a measured parameter, as the app's
-// _asmFormulaValueForCol (13a): readings of the primary run condition (the one
+// _asmFormulaValueForCol (12v): 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) {