formlab-mcp 0.6.22 → 0.6.23

package/README.md

@@ -56,13 +56,13 @@ Ask Claude (or another MCP client) things like:
 | `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 |
 | `find_by_smarts` | SMARTS-pattern substructure search across every ingredient with a SMILES. Requires `@rdkit/rdkit` (optional dependency — install with `npm install @rdkit/rdkit` in `mcp/` if you get a "not installed" error). Examples: `c1ccccc1` (any aromatic 6-ring), `[OX2H1]` (any hydroxyl), `C(=O)O` (carboxylic acid), `[F,Cl,Br,I]` (any halogen). |
 | `list_equipment` | Filtered list of the Equipment registry (mixers, ovens, viscometers, balances…). Filters: `category`, `status`, `manufacturer`, `name_contains` |
-| `get_equipment` | Full equipment record + a summary of where it's used (panels, step presets, test methods, formulas, batches) |
+| `get_equipment` | Full equipment record + `usedIn` (panels, step presets, test methods, formula steps, batches, testReports resolved to it), `usage` (reports / formulas / batches / samples / pass rate / top formulas) and `measured` (per parameter: mean here vs mean on other instruments, biasPct) |
 | `list_test_methods` | Filtered list of Test Methods (the parameter library). Filter by `analyte` (the property measured, e.g. `Viscosity` — finds every method for it), `category`, `name_contains`, `include_retired` |
-| `get_test_method` | Full method definition (SOP / sample prep / equipment / calculation / acceptance spec) + sibling methods sharing its analyte |
+| `get_test_method` | One Test Method: full definition, run conditions, analyte siblings, using panels, plus `usage`, `valueSummary` (mean / sd / min / max) and `byInstrument` |
 | `list_step_presets` | Filtered list of Step Presets (reusable procedure steps: duration / temp / RPM / equipment). Filters: `industry`, `name_contains` |
 | `get_step_preset` | Full step-preset record incl. the multi-value equipment list (`{name, equipmentId}`) |
 | `list_test_panels` | Filtered list of Test Panels (reusable column-sets — the parameters measured together on a sample). Filters: `industry`, `name_contains` |
-| `get_test_panel` | Full panel record — ordered parameter list (each with resolved Test Method UID, unit, spec) + instruments |
+| `get_test_panel` | One Test Panel: ordered parameters with resolved method UIDs + specs, plus `usage` (reports created from it) and `performanceByParameter` |
 | `list_projects` | Filtered list of projects (the buckets formulations are filed under) + per-project formulation count. Filters: `status`, `name_contains` |
 | `get_project` | Full project record + the formulations filed under it |
 | `list_notebook_entries` | ELN feed — dated authored notes attached to records. Filters: `entity_type`, `entity_id`, `author`, `text_contains`, `since`, `until` |

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.22",
+  "version": "0.6.23",
   "mcpName": "io.github.juliu1980/formlab-mcp",
-  "description": "Read-only Model Context Protocol server for FormLab — lets Claude (and other MCP clients) read and analyze your FormLab data, from a local export file OR your live cloud workspace.",
+  "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",
   "bin": {
     "formlab-mcp": "./index.js"

package/tools/analytics.js

@@ -913,6 +913,7 @@ const get_stability = {
   },
 };
 
+export { _evalPassFail };
 export const tools = {
   list_test_results,
   get_test_result,

package/tools/library.js

@@ -12,6 +12,55 @@
 // ============================================================
 
 import { getStore, resolveById } from '../data.js';
+import { _evalPassFail } from './analytics.js';
+
+// ── Usage roll-ups (mirror the Usage tabs on the Panel / Method / Equipment
+//    detail pages) ────────────────────────────────────────────────────────
+// Resolve a measurement's instrument the way the app does: named on the row →
+// the parameter's Test Method equipment → the report's run default.
+function _resolveInstrument(m, t, db) {
+  if (m.equipmentId || m.instrument) return { equipmentId: m.equipmentId || '', name: m.instrument || '', source: 'row' };
+  const pm = m.parameterId ? (db.parameters || []).find(p => p.id === m.parameterId)
+    : (db.parameters || []).find(p => _norm(p.name) === _norm(m.parameter));
+  if (pm && (pm.equipmentId || pm.equipment)) return { equipmentId: pm.equipmentId || '', name: pm.equipment || '', source: 'method' };
+  if (t && (t.equipmentId || t.instrument)) return { equipmentId: t.equipmentId || '', name: t.instrument || '', source: 'run' };
+  return { equipmentId: '', name: '', source: '' };
+}
+function _num(m) { const v = parseFloat(m && m.value); return Number.isFinite(v) ? v : null; }
+function _mean(a) { return a.length ? a.reduce((x, y) => x + y, 0) / a.length : null; }
+function _sd(a) { if (a.length < 2) return null; const mu = _mean(a); return Math.sqrt(a.reduce((acc, x) => acc + (x - mu) ** 2, 0) / (a.length - 1)); }
+function _r(v, d = 3) { return v == null ? null : +v.toFixed(d); }
+// Where a set of reports (optionally restricted to measurements passing
+// `measFilter`) landed: totals + by-formula breakdown (top 10). `fails` uses the
+// measurement's own acceptance criteria (panel spec inheritance is app-side).
+function _usageRollup(db, tests, measFilter) {
+  const sById = new Map((db.samples || []).map(s => [s.id, s]));
+  const bById = new Map((db.batches || []).map(b => [b.id, b]));
+  const fById = new Map((db.formulations || []).map(f => [f.id, f]));
+  const date = t => String(t.testDate || (t.createdAt || '').slice(0, 10) || '');
+  const byF = new Map(); const forms = new Set(), batches = new Set(), samples = new Set(), labs = new Set();
+  let readings = 0, fails = 0, withSpec = 0, last = '';
+  tests.forEach(t => {
+    const s = sById.get(t.sampleId) || null; const b = s ? bById.get(s.batchId) : null;
+    const f = (s && s.formulationId) ? fById.get(s.formulationId) : (b ? fById.get(b.formulationId) : null);
+    if (s) samples.add(s.id); if (b) batches.add(b.id); if (f) forms.add(f.id); if (t.lab) labs.add(t.lab);
+    const d = date(t); if (d > last) last = d;
+    let tf = 0;
+    (t.measurements || []).filter(m => !measFilter || measFilter(m, t)).forEach(m => {
+      readings++;
+      const pf = _evalPassFail(m); if (pf !== 'no-criteria' && pf !== 'untested') withSpec++; if (pf === 'fail') { fails++; tf++; }
+    });
+    const key = f ? f.id : '(no formula)';
+    if (!byF.has(key)) byF.set(key, { formula: f ? (f.uid || f.name) : null, formulaName: f ? f.name : null, reports: 0, lastRun: '', fails: 0 });
+    const g = byF.get(key); g.reports++; if (d > g.lastRun) g.lastRun = d; g.fails += tf;
+  });
+  return {
+    reports: tests.length, readings, lastUsed: last || null,
+    formulas: forms.size, batches: batches.size, samples: samples.size, labs: labs.size,
+    fails, passRate: withSpec ? _r(100 * (withSpec - fails) / withSpec, 0) : null,
+    byFormula: [...byF.values()].sort((a, b) => b.reports - a.reports).slice(0, 10),
+  };
+}
 
 const _norm = (s) => String(s == null ? '' : s).toLowerCase();
 const _clampLimit = (n) => Math.min(1000, Math.max(1, n || 100));
@@ -99,7 +148,7 @@ const list_equipment = {
 const get_equipment = {
   definition: {
     name: 'get_equipment',
-    description: 'Get one equipment record by UID (e.g. EQP-001) or id, including a summary of everywhere it is referenced (test panels, step presets, test methods, formulas, batches).',
+    description: 'Get one equipment record by UID (e.g. EQP-001) or id, including `usedIn` (everywhere its DEFINITION is referenced: test panels, step presets, test methods, formula steps, batches, plus testReports = reports with a measurement resolved to it), `usage` (those reports: totals, last used, distinct formulas/batches/samples, pass rate, top formulas) and `measured` (per parameter: readings and mean on this unit vs readings/mean on all OTHER instruments, with biasPct — the calibration question). Instrument resolution follows the app: named on the measurement → the Test Method\'s equipment → the report\'s run default.',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Equipment UID or internal id.' } },
@@ -110,7 +159,25 @@ const get_equipment = {
     const { db } = getStore();
     const e = resolveById('equipment', args.id);
     if (!e) return { error: `No equipment found for "${args.id}".` };
-    return { ...(_trimEquipment(e)), usedIn: _equipUsage(e, db) };
+    // Measurements whose RESOLVED instrument is this unit (row → method → run).
+    const nm = _norm(e.name);
+    const mine = (m, t) => { const r = _resolveInstrument(m, t, db); return r.equipmentId ? r.equipmentId === e.id : (!!nm && _norm(r.name) === nm); };
+    const tests = (db.testResults || []).filter(t => (t.measurements || []).some(m => mine(m, t)));
+    const here = new Map(), fleet = new Map();
+    (db.testResults || []).forEach(t => (t.measurements || []).forEach(m => {
+      const pn = (m.parameter || '').trim(); if (!pn) return;
+      const v = _num(m); const isMine = mine(m, t); const bucket = isMine ? here : fleet;
+      if (!bucket.has(pn)) bucket.set(pn, { parameter: pn, readings: 0, vals: [], fails: 0 });
+      const g = bucket.get(pn); g.readings++; if (v != null) g.vals.push(v); if (isMine && _evalPassFail(m) === 'fail') g.fails++;
+    }));
+    const measured = [...here.values()].map(g => {
+      const f = fleet.get(g.parameter); const mh = _mean(g.vals), me = f ? _mean(f.vals) : null;
+      return { parameter: g.parameter, readings: g.readings, mean: _r(mh), fails: g.fails, readingsElsewhere: f ? f.readings : 0, meanElsewhere: _r(me),
+        biasPct: (mh != null && me != null && me !== 0) ? _r((mh - me) / Math.abs(me) * 100, 1) : null };
+    }).sort((a, b) => b.readings - a.readings);
+    const usedIn = _equipUsage(e, db);
+    usedIn.testReports = tests.length;
+    return { ...(_trimEquipment(e)), usedIn, usage: _usageRollup(db, tests, mine), measured };
   },
 };
 
@@ -187,7 +254,7 @@ const list_test_methods = {
 const get_test_method = {
   definition: {
     name: 'get_test_method',
-    description: 'Get one Test Method by UID (e.g. PARAM-001) or id — full definition including SOP / sample prep / equipment / calculation / acceptance spec, the declared runConditions this method varies by (the vocabulary — e.g. Storage temp/RH, spindle RPM; each measurement captures a value per condition), plus sibling methods that share its analyte (the same property measured at other conditions) and the Test Panels that use this method.',
+    description: 'Get one Test Method by UID (e.g. PARAM-001) or id — full definition including SOP / sample prep / equipment / calculation / acceptance spec, the declared runConditions this method varies by (the vocabulary — e.g. Storage temp/RH, spindle RPM; each measurement captures a value per condition), sibling methods that share its analyte, the Test Panels that use it, plus `usage` (reports / readings linked to this method: totals, last used, distinct formulas/batches/samples, pass rate, top formulas), `valueSummary` (mean / sd / min / max over numeric readings) and `byInstrument` (readings, mean and fails per resolved instrument — a mean that differs between units is a calibration question).',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Test Method UID or internal id.' } },
@@ -208,7 +275,19 @@ const get_test_method = {
       (row.parameterId && row.parameterId === p.id) ||
       (!row.parameterId && _norm(row.parameter || row.name) === nm)
     )).map(t => t.uid || t.name).slice(0, 40);
-    return { ...(_trimMethod(p, { full: true })), analyteSiblings: siblings, usingPanels };
+    // Usage = every measurement linked to this method (by id, else by exact name).
+    const match = (m) => (m.parameterId && m.parameterId === p.id) || (!m.parameterId && _norm(m.parameter) === nm);
+    const tests = (db.testResults || []).filter(r => (r.measurements || []).some(match));
+    const vals = [], byInst = new Map();
+    tests.forEach(r => (r.measurements || []).filter(match).forEach(m => {
+      const v = _num(m); if (v != null) vals.push(v);
+      const inst = _resolveInstrument(m, r, db); const key = inst.name || inst.equipmentId || '(unresolved)';
+      if (!byInst.has(key)) byInst.set(key, { instrument: key, readings: 0, vals: [], fails: 0 });
+      const g = byInst.get(key); g.readings++; if (v != null) g.vals.push(v); if (_evalPassFail(m) === 'fail') g.fails++;
+    }));
+    const byInstrument = [...byInst.values()].map(g => ({ instrument: g.instrument, readings: g.readings, mean: _r(_mean(g.vals)), fails: g.fails })).sort((a, b) => b.readings - a.readings);
+    const valueSummary = { readings: vals.length, mean: _r(_mean(vals)), sd: _r(_sd(vals)), min: vals.length ? Math.min(...vals) : null, max: vals.length ? Math.max(...vals) : null, unit: p.defaultUnit || '' };
+    return { ...(_trimMethod(p, { full: true })), analyteSiblings: siblings, usingPanels, usage: _usageRollup(db, tests, match), valueSummary, byInstrument };
   },
 };
 
@@ -356,7 +435,7 @@ const list_test_panels = {
 const get_test_panel = {
   definition: {
     name: 'get_test_panel',
-    description: 'Get one Test Panel by UID (e.g. TMPL-001) or id — full ordered parameter list (each with its resolved Test Method UID, unit, and spec), instruments, and notes.',
+    description: 'Get one Test Panel by UID (e.g. TMPL-001) or id — full ordered parameter list (each with its resolved Test Method UID, unit, and spec), instruments, notes, plus `usage` (reports created from this panel: totals, last used, distinct formulas/batches/samples, pass rate, top formulas) and `performanceByParameter` (readings / fails per parameter). Usage counts reports created from the panel, not parameter overlap.',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Test Panel UID or internal id.' } },
@@ -367,7 +446,19 @@ const get_test_panel = {
     const { db } = getStore();
     const t = resolveById('templates', args.id);
     if (!t) return { error: `No test panel found for "${args.id}".` };
-    return _trimPanel(t, db, { full: true });
+    // Usage = reports created FROM this panel (templateId) — not parameter overlap.
+    const tests = (db.testResults || []).filter(r => r.templateId === t.id);
+    const perf = (t.parameters || []).map(row => {
+      const nm = _norm(row.parameter || row.name), pid = row.parameterId || '';
+      let n = 0, fails = 0, withSpec = 0;
+      tests.forEach(r => (r.measurements || []).forEach(m => {
+        const hit = (pid && m.parameterId === pid) || ((!m.parameterId || !pid) && _norm(m.parameter) === nm);
+        if (!hit) return; n++;
+        const pf = _evalPassFail(m); if (pf !== 'no-criteria' && pf !== 'untested') withSpec++; if (pf === 'fail') fails++;
+      }));
+      return { parameter: row.parameter || row.name, readings: n, fails, failRatePct: withSpec ? _r(100 * fails / withSpec, 0) : null };
+    });
+    return { ...(_trimPanel(t, db, { full: true })), usage: _usageRollup(db, tests, null), performanceByParameter: perf };
   },
 };