formlab-mcp 0.6.6 → 0.6.8

package/README.md

@@ -145,7 +145,7 @@ Or for local-dev (from the repo):
 }
 ```
 
-Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 33 tools become callable in any conversation.
+Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 34 tools become callable in any conversation.
 
 ## Wire it up to Claude Code
 

package/package.json

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

package/tools/analytics.js

@@ -7,6 +7,7 @@
 //   - get_coverage_matrix    (which items × parameters have been tested)
 //   - list_doe_designs       (saved design records — the intent behind the runs)
 //   - get_doe_design         (one design in full, incl. its run matrix)
+//   - get_stability          (drift + I-chart + shelf-life, split by condition)
 // ============================================================
 
 import { getStore, resolveById, flattenComposition } from '../data.js';
@@ -611,7 +612,7 @@ const list_doe_designs = {
 const get_doe_design = {
   definition: {
     name: 'get_doe_design',
-    description: 'Get one saved DOE design in full: factors and ranges, constraints, the model it was optimised for, generation settings (run budget, replicates, centre points, seed), D-efficiency, and the complete run matrix with the formulation each run became. Everything needed to reproduce or audit the design.',
+    description: 'Get one saved DOE design in full: factors and ranges, constraints, the model it was optimized for, generation settings (run budget, replicates, center points, seed), D-efficiency, and the complete run matrix with the formulation each run became. Everything needed to reproduce or audit the design.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -686,6 +687,174 @@ const get_doe_design = {
   },
 };
 
+// ============================================================
+// get_stability — grounded stability / shelf-life analysis
+// ------------------------------------------------------------
+// The MCP analog of the in-app Stability & Trends view: for one entity
+// (formulation / sample / batch) × parameter, it returns the DETERMINISTIC
+// numbers — drift, I-chart, spec status, and an ICH-flavored shelf-life
+// projection — split by storage condition when captured. Deterministic
+// facts here, so the model narrates rather than re-derives the regression.
+// ============================================================
+const _MS_PER_MONTH = 30.4375 * 86400000;
+const _round = (v, d = 4) => (v == null || !Number.isFinite(v)) ? null : +v.toFixed(d);
+
+function _ols(xs, ys) {
+  const n = xs.length;
+  if (n < 2 || ys.length !== n) return null;
+  const mx = xs.reduce((a, b) => a + b, 0) / n, my = ys.reduce((a, b) => a + b, 0) / n;
+  let num = 0, den = 0, ssTot = 0;
+  for (let i = 0; i < n; i++) { num += (xs[i] - mx) * (ys[i] - my); den += (xs[i] - mx) ** 2; ssTot += (ys[i] - my) ** 2; }
+  if (den === 0) return null;
+  const slope = num / den, intercept = my - slope * mx;
+  let ssRes = 0;
+  for (let i = 0; i < n; i++) { const pr = intercept + slope * xs[i]; ssRes += (ys[i] - pr) ** 2; }
+  return { slope, intercept, r2: ssTot === 0 ? 1 : 1 - ssRes / ssTot };
+}
+
+// Individuals (I) control chart: mean ± 3σ, σ from the average moving range.
+function _iChart(ys) {
+  const n = ys.length;
+  if (n < 2) return null;
+  const mean = ys.reduce((a, b) => a + b, 0) / n;
+  let mrSum = 0;
+  for (let i = 1; i < n; i++) mrSum += Math.abs(ys[i] - ys[i - 1]);
+  const sigma = (mrSum / (n - 1)) / 1.128;   // d2 for n=2
+  const ucl = mean + 3 * sigma, lcl = mean - 3 * sigma;
+  const ooc = [];
+  ys.forEach((y, i) => { if (sigma > 0 && (y > ucl || y < lcl)) ooc.push(i + 1); });
+  return { mean, sigma, ucl, lcl, ooc };
+}
+
+// Shelf life: fit vs elapsed months, extrapolate to the spec limit the trend
+// heads toward. Point-estimate crossing + the conservative 95% CI-bound crossing.
+function _shelfLife(points, spec) {
+  if (!points || points.length < 3 || (spec.min == null && spec.max == null)) return null;
+  const t0 = Math.min(...points.map(p => p.date.getTime()));
+  const xs = points.map(p => (p.date.getTime() - t0) / _MS_PER_MONTH);
+  const ys = points.map(p => p.value);
+  const fit = _ols(xs, ys);
+  if (!fit || Math.abs(fit.slope) < 1e-9) return null;
+  const limit = fit.slope < 0 ? spec.min : spec.max;
+  if (limit == null) return null;
+  const edge = fit.slope < 0 ? 'lower' : 'upper';
+  const lastX = Math.max(...xs);
+  const remaining = (limit - fit.intercept) / fit.slope - lastX;
+  const n = xs.length, mx = xs.reduce((a, b) => a + b, 0) / n;
+  const ssX = xs.reduce((a, b) => a + (b - mx) ** 2, 0);
+  let ssR = 0; xs.forEach((x, i) => { const pr = fit.intercept + fit.slope * x; ssR += (ys[i] - pr) ** 2; });
+  const sResid = Math.sqrt(ssR / Math.max(1, n - 2));
+  const tcrit = n > 30 ? 1.96 : n > 10 ? 2.1 : 2.5;
+  const sign = fit.slope < 0 ? -1 : 1;
+  const bound = (tt) => fit.intercept + fit.slope * tt + sign * tcrit * sResid * Math.sqrt(1 / n + ((tt - mx) ** 2) / Math.max(1e-9, ssX));
+  let ciRemaining = null;
+  for (let tt = lastX; tt <= lastX + 120; tt += 0.25) {
+    if (fit.slope < 0 ? bound(tt) <= limit : bound(tt) >= limit) { ciRemaining = tt - lastX; break; }
+  }
+  return { edge, limit, remainingMonths: remaining, ciRemainingMonths: ciRemaining, r2: fit.r2 };
+}
+
+const get_stability = {
+  definition: {
+    name: 'get_stability',
+    description: 'Grounded stability / shelf-life analysis for one entity × parameter — the deterministic numbers behind the Stability & Trends view. Pass a formulation (pools all its samples), a sample (that sample over time), or a batch (pools its samples) by id or UID, plus a parameter name. Returns the time series, drift (per-month slope + R²), an individuals control chart (mean ± 3σ + out-of-control points), spec status, and an ICH-flavored projected shelf life (linear extrapolation to the spec crossing: point estimate + the conservative 95%-confidence-bound crossing). When measurements carry run conditions (e.g. Storage 25 °C vs 40 °C) it splits into one series per condition — a true accelerated-vs-ambient comparison. Use these figures directly; do not re-derive the regression.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        entity_id: { type: 'string', description: 'A formulation, sample, or batch — id or UID (e.g. FRM-002, SMP-007, BTC-001). The type is auto-detected and sets the pooling level.' },
+        parameter: { type: 'string', description: 'The measured parameter to analyze (case-insensitive, e.g. "Niacinamide assay").' },
+        by_condition: { type: 'boolean', description: 'Split the series by captured storage condition (default true). Set false to pool all conditions into one trend.' },
+      },
+      required: ['entity_id', 'parameter'],
+    },
+  },
+  handler: async (args) => {
+    const db = getStore().db;
+    let entity = null, entityType = null;
+    for (const [type, coll] of [['formulation', 'formulations'], ['sample', 'samples'], ['batch', 'batches']]) {
+      const e = (db[coll] || []).find(x => x.id === args.entity_id || x.uid === args.entity_id);
+      if (e) { entity = e; entityType = type; break; }
+    }
+    if (!entity) return { error: `No formulation, sample, or batch found for "${args.entity_id}".` };
+    const sampleIds = entityType === 'sample'
+      ? new Set([entity.id])
+      : new Set((db.samples || []).filter(s => (entityType === 'batch' ? s.batchId : s.formulationId) === entity.id).map(s => s.id));
+
+    const paramLc = (args.parameter || '').trim().toLowerCase();
+    if (!paramLc) return { error: 'parameter is required.' };
+    const points = [];
+    let specMin = null, specMax = null, unit = '';
+    (db.testResults || []).filter(t => sampleIds.has(t.sampleId)).forEach(t => {
+      const dStr = t.testDate || (t.createdAt ? String(t.createdAt).slice(0, 10) : null);
+      if (!dStr) return;
+      const date = new Date(dStr + (t.testTime && /^\d{4}-\d{2}-\d{2}$/.test(dStr) ? 'T' + t.testTime : ''));
+      if (!Number.isFinite(date.getTime())) return;
+      (t.measurements || []).forEach(m => {
+        if ((m.parameter || '').trim().toLowerCase() !== paramLc) return;
+        let value = parseFloat(m.value);
+        if (!Number.isFinite(value) && Array.isArray(m.points) && m.points.length) {
+          const last = m.points[m.points.length - 1]; value = parseFloat(last && (last.value ?? last.y));   // time-series → final
+        }
+        if (!Number.isFinite(value)) return;
+        if (m.unit && !unit) unit = m.unit;
+        const ac = m.acceptanceCriteria;
+        if (ac) { if (Number.isFinite(ac.min)) specMin = specMin == null ? ac.min : Math.max(specMin, ac.min); if (Number.isFinite(ac.max)) specMax = specMax == null ? ac.max : Math.min(specMax, ac.max); }
+        const cond = (m.conditions && Object.keys(m.conditions).length)
+          ? Object.entries(m.conditions).map(([k, v]) => `${k} ${v}`).join(' · ') : '';
+        points.push({ date, value, cond });
+      });
+    });
+    // Spec fallback to the Test Method library entry when no measurement carried one.
+    if (specMin == null && specMax == null) {
+      const pdef = (db.parameters || []).find(p => (p.name || '').trim().toLowerCase() === paramLc);
+      if (pdef && pdef.acceptanceCriteria) { specMin = pdef.acceptanceCriteria.min ?? null; specMax = pdef.acceptanceCriteria.max ?? null; }
+    }
+    points.sort((a, b) => a.date - b.date);
+    if (!points.length) return { error: `No dated "${args.parameter}" measurements on ${entity.uid || entity.id}.` };
+
+    const spec = { min: specMin, max: specMax };
+    const analyze = (pts) => {
+      const ys = pts.map(p => p.value);
+      const n = ys.length;
+      const out = { points: n, from: pts[0].date.toISOString().slice(0, 10), to: pts[n - 1].date.toISOString().slice(0, 10), values: ys.map(v => _round(v, 6)), latest: _round(ys[n - 1], 6) };
+      if (n < 2) { out.note = 'Fewer than 2 points — no trend/shelf-life.'; return out; }
+      const fit = _ols(pts.map((_, i) => i), ys);
+      if (fit) {
+        const days = (pts[n - 1].date - pts[0].date) / 86400000;
+        const perMonth = days > 0 ? (fit.slope * (n - 1) / days) * 30 : 0;
+        out.drift = { perMonth: _round(perMonth, 4), r2: _round(fit.r2, 3), direction: perMonth > 0 ? 'increasing' : perMonth < 0 ? 'decreasing' : 'flat' };
+      }
+      const ic = _iChart(ys);
+      if (ic) out.controlChart = { mean: _round(ic.mean), ucl: _round(ic.ucl), lcl: _round(ic.lcl), sigma: _round(ic.sigma), outOfControlPoints: ic.ooc };
+      if (spec.min != null || spec.max != null) out.spec = { ...spec, latestInSpec: (spec.min == null || ys[n - 1] >= spec.min) && (spec.max == null || ys[n - 1] <= spec.max) };
+      const sl = _shelfLife(pts, spec);
+      if (sl) out.shelfLife = {
+        headingToward: `${sl.edge} spec (${_round(sl.limit)})`,
+        remainingMonths: _round(sl.remainingMonths, 1),
+        ci95Months: sl.ciRemainingMonths != null ? _round(sl.ciRemainingMonths, 1) : null,
+        r2: _round(sl.r2, 2), basis: 'linear extrapolation to spec crossing',
+      };
+      return out;
+    };
+
+    const split = args.by_condition !== false && points.some(p => p.cond);
+    let series;
+    if (split) {
+      const byC = new Map();
+      points.forEach(p => { const k = p.cond || '(no condition)'; if (!byC.has(k)) byC.set(k, []); byC.get(k).push(p); });
+      series = [...byC.keys()].sort().map(k => ({ condition: k, ...analyze(byC.get(k)) }));
+    } else {
+      series = [{ condition: null, ...analyze(points) }];
+    }
+
+    return {
+      entity: { type: entityType, uid: entity.uid, name: entity.name || entity.uid },
+      parameter: args.parameter, unit, spec, pointCount: points.length, byCondition: split, series,
+      note: 'shelfLife.remainingMonths is the point-estimate months from the last test to the spec crossing; ci95Months is the conservative (ICH-style) estimate where the 95% confidence bound crosses spec. Numbers are computed here — narrate them, do not recompute.',
+    };
+  },
+};
+
 export const tools = {
   list_test_results,
   get_test_result,
@@ -694,4 +863,5 @@ export const tools = {
   get_coverage_matrix,
   list_doe_designs,
   get_doe_design,
+  get_stability,
 };

package/tools/lab.js

@@ -8,6 +8,44 @@
 
 import { getStore, resolveById } from '../data.js';
 
+// --- Self-contained unit conversion + actual-volume derivation ---------------
+// The MCP server has no access to the app's cost.js helpers, so a small local
+// factor table covers the common units. Mirrors js/views/batches.js:
+// _batchActualMassKg / _batchActualVolume — actual volume is measured directly
+// when logged, else actual mass ÷ measured finished-product density. Never a
+// sum of per-ingredient volumes (volume isn't additive; mass is).
+const _MASS_TO_KG = { mg: 1e-6, cg: 1e-5, dg: 1e-4, g: 1e-3, hg: 0.1, kg: 1, oz: 0.0283495, lb: 0.453592, stone: 6.35029, t: 1000, ton: 1000, tonne: 1000, grain: 6.47989e-5, 'µg': 1e-9, ug: 1e-9, mcg: 1e-9 };
+const _VOL_TO_L = { 'µl': 1e-6, ul: 1e-6, ml: 1e-3, cl: 1e-2, dl: 0.1, l: 1, gal: 3.78541, fl_oz: 0.0295735, floz: 0.0295735, pt: 0.473176, qt: 0.946353, tsp: 0.00492892, tbsp: 0.0147868, cup: 0.236588 };
+function _massToKg(v, u) { const f = _MASS_TO_KG[String(u || '').trim().toLowerCase()]; return (f != null && isFinite(v)) ? v * f : null; }
+function _volToL(v, u) { const f = _VOL_TO_L[String(u || '').trim().toLowerCase()]; return (f != null && isFinite(v)) ? v * f : null; }
+function _batchActualMassKg(b) {
+  const y = parseFloat(b.actualYield);
+  if (isFinite(y)) { const kg = _massToKg(y, b.unit); if (kg != null) return kg; }
+  if (Array.isArray(b.actualComposition)) {
+    let t = 0, any = false;
+    for (const c of b.actualComposition) { const kg = _massToKg(parseFloat(c.amount), c.unit); if (kg != null) { t += kg; any = true; } }
+    if (any) return t;
+  }
+  return null;
+}
+function _batchActualVolume(b) {
+  const mv = parseFloat(b.measuredVolume);
+  if (isFinite(mv) && mv > 0) { const L = _volToL(mv, b.measuredVolumeUnit || 'L'); if (L != null) return { liters: L, source: 'measured' }; }
+  const d = parseFloat(b.measuredDensity), m = _batchActualMassKg(b);
+  if (isFinite(d) && d > 0 && m != null) return { liters: m / d, source: 'derived' };
+  return null;
+}
+// Public shape for a batch's actual volume (or null). Includes the density used
+// (derived case) or implied by the measurement (measured case) for QC.
+function _actualVolumeInfo(b) {
+  const av = _batchActualVolume(b);
+  if (!av) return null;
+  const out = { liters: +av.liters.toFixed(4), unit: 'L', source: av.source };
+  if (av.source === 'derived') { const d = parseFloat(b.measuredDensity); if (isFinite(d)) out.densityUsed = d; }
+  else { const m = _batchActualMassKg(b); if (m != null && av.liters > 0) out.impliedDensity = +(m / av.liters).toFixed(4); }
+  return out;
+}
+
 function _trimBatch(b, formulationsById) {
   if (!b) return null;
   const f = b.formulationId ? formulationsById.get(b.formulationId) : null;
@@ -20,6 +58,14 @@ function _trimBatch(b, formulationsById) {
     targetQuantity: b.targetQuantity ?? null,
     unit: b.unit || '',
     actualYield: b.actualYield ?? null,
+    // Finished-product density (g/mL === kg/L), measured on the blend, + the
+    // derived/measured actual VOLUME (mass is the additive quantity; volume is
+    // measured or derived from density, never summed across ingredients).
+    measuredDensity: b.measuredDensity ?? null,
+    densityTempC: (b.densityTemp != null && b.densityTemp !== '') ? b.densityTemp : null,
+    measuredVolume: b.measuredVolume ?? null,
+    measuredVolumeUnit: b.measuredVolumeUnit || '',
+    actualVolume: _actualVolumeInfo(b),
     preparedDate: b.preparedDate || '',
     preparedBy: b.preparedBy || '',
     process: b.process || '',
@@ -95,7 +141,7 @@ const list_batches = {
 const get_batch = {
   definition: {
     name: 'get_batch',
-    description: 'Get full details for a single batch including its actual composition (as-prepared, when logged), child samples, lineage (parent / sub-blend parents), and inventory consumption note. Accepts internal id or UID.',
+    description: 'Get full details for a single batch including its actual composition (as-prepared, when logged), child samples, lineage (parent / sub-blend parents), inventory consumption note, and finished-product density + actual volume (measured directly or derived as actual mass ÷ measured density — never summed from per-ingredient volumes). Accepts internal id or UID.',
     inputSchema: {
       type: 'object',
       properties: {