formlab-mcp 0.6.67 → 0.6.68

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -52,7 +52,7 @@ Ask Claude (or another MCP client) things like:
52
52
  | `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` |
53
53
  | `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 |
54
54
  | `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 |
55
- | `get_stability` | Grounded stability / shelf-life analysis for a formulation, sample or batch × parameter (auto-detected): time-series, drift (per-month slope + R²), an I-chart (mean ±3σ + out-of-control points), spec status, and an ICH-Q1E-flavored projected shelf life (point + 95%-CI crossing), all on **one point per test date per run condition** (replicates averaged, never separate time points), split by storage condition. A ranked-scale (ordinal) or text parameter returns its step / pass-fail series instead: per-condition points, firstFail, latest, scaleShift. Also the app's **Time points** (per condition: tested time points, skipped pulls, the next pull with its due date and whether it's overdue, on the formula's own pull schedule, in months or weeks, or the standard one; `as_of`) and **Arrhenius** (rates at the storage temperatures → the rate, Ea, Q10 and shelf life at `predict_at_c`, zero or first `order`, with 95% CIs and a verdict against the target), and per series the **moving range** (MR̄, its limit, the jumps above it) |
55
+ | `get_stability` | Grounded stability / shelf-life analysis for a formulation, sample or batch × parameter (auto-detected): time-series, drift (per-month slope + R²), an I-chart (mean ±3σ + out-of-control points), spec status, and an ICH-Q1E-flavored projected shelf life (point + 95%-CI crossing), all on **one point per test date per run condition** (replicates averaged, never separate time points), split by storage condition. A ranked-scale (ordinal) or text parameter returns its step / pass-fail series instead: per-condition points, firstFail, latest, scaleShift. Also the app's **Time points** (per condition: tested time points, skipped pulls, the next pull with its due date and whether it's overdue, on the formula's own pull schedule, in months or weeks, or the standard one; `as_of`) and **Arrhenius** (rates at the storage temperatures → the rate, Ea, Q10 and shelf life at `predict_at_c`, zero or first `order`, with 95% CIs and a verdict against the target), and per series the **moving range** (MR̄, its limit, the jumps above it). Leave out `parameter` for **All parameters**: every parameter's spec status and months to spec, out of spec first, and the one that limits shelf life |
56
56
  | `list_stability_pulls` | Stability pulls due across the whole workspace (the app's Needs Attention row): every formula on a study, its next pull per storage condition overdue or due within `within_days` (default 7), on its own pull schedule or the standard one, with the samples to pull; a test of any parameter counts as the pull; studies more than 60 days late listed apart as stopped |
57
57
  | `get_design_space` | COMPOSITION design space for one project, several (`projects`) or any formula list (`formulas`, across projects — like the app's Scope → DOE Matrix): which ingredients vary and over what observed wt-% ranges (ranked), an occupied-region summary ("where you've been"), the biggest untested **interior gap** as ready-to-seed DOE ranges (a combination you could have made but skipped), and an optional standardised **2-component PCA** of all varying ingredients — loadings, variance-explained, scree, and a full-dimensional gap. Optional `axes` (choose the 2–3 axes), `by_role` (map ingredients summed by primary Function, e.g. Pigment / Solvent / Film Former — no gap, roles aren't DOE factors) and `property` (highest / lowest formula plus the ingredients whose level tracks it, Spearman ρ). Reports formulas that aren't on the map and the spread on it. Matches the in-app Design Space Viewer exactly. Answers *"where haven't I explored?"* / *"what should I formulate next?"* |
58
58
  | `list_doe_designs` | Saved DOE designs — the *recipe* behind each batch of runs: design type, factors + ranges, constraints, run count, D-efficiency. Filters: `project`, `design_type`, `constrained_only`, `name_contains` |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "formlab-mcp",
3
- "version": "0.6.67",
3
+ "version": "0.6.68",
4
4
  "mcpName": "io.github.juliu1980/formlab-mcp",
5
5
  "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.",
6
6
  "homepage": "https://formvix.com/mcp",
package/server.json CHANGED
@@ -2,13 +2,13 @@
2
2
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
3
3
  "name": "io.github.juliu1980/formlab-mcp",
4
4
  "description": "Read-only MCP server for FormLab formulation data: a local export file or your live cloud workspace.",
5
- "version": "0.6.67",
5
+ "version": "0.6.68",
6
6
  "websiteUrl": "https://formvix.com/mcp",
7
7
  "packages": [
8
8
  {
9
9
  "registryType": "npm",
10
10
  "identifier": "formlab-mcp",
11
- "version": "0.6.67",
11
+ "version": "0.6.68",
12
12
  "runtimeHint": "npx",
13
13
  "transport": {
14
14
  "type": "stdio"
@@ -1663,21 +1663,73 @@ function _mcpArrhenius(points, spec, atC, order, targetMonths) {
1663
1663
  return out;
1664
1664
  }
1665
1665
 
1666
+ // get_stability without a parameter: the app's All parameters plot (FormLab 47i) as numbers. Every parameter the
1667
+ // entity was tested for, each run through get_stability itself, out of spec now first, then by months to spec (the
1668
+ // earliest condition's projection from T0); the first to cross is the parameter that limits shelf life. The app's
1669
+ // order before that: numeric before graded, then most readings (_stabAvailableParameters).
1670
+ async function _mcpAllParameters(entity, entityType, sampleIds, args, db) {
1671
+ const names = new Map(); // lower case → { name, n, numeric }
1672
+ (db.testResults || []).filter(t => sampleIds.has(t.sampleId)).forEach(t => (t.measurements || []).forEach(m => {
1673
+ const name = (m.parameter || '').trim(); if (!name) return;
1674
+ const k = name.toLowerCase(), ty = _mcpMeasType(m);
1675
+ if (!names.has(k)) names.set(k, { name, n: 0, numeric: false });
1676
+ const e = names.get(k); e.n++; if (ty !== 'ordinal' && ty !== 'categorical') e.numeric = true;
1677
+ }));
1678
+ const order = [...names.values()].sort((a, b) => (b.numeric - a.numeric) || (b.n - a.n));
1679
+ const rows = [];
1680
+ for (const p of order) {
1681
+ const r = await get_stability.handler({ ...args, parameter: p.name });
1682
+ if (!r || r.error || !(r.series || []).length) continue;
1683
+ const graded = r.kind === 'ordinal' || r.kind === 'categorical';
1684
+ const failing = r.series.filter(se => graded ? (se.latest && se.latest.pf === 'fail') : se._latestFail).map(se => se.condition);
1685
+ const shelf = graded ? [] : r.series.filter(se => se.shelfLife && se.shelfLife._pointTotal != null)
1686
+ .sort((a, b) => a.shelfLife._pointTotal - b.shelfLife._pointTotal);
1687
+ const first = shelf[0] || null;
1688
+ rows.push({
1689
+ parameter: p.name, kind: graded ? r.kind : 'numeric', ...(r.unit ? { unit: r.unit } : {}),
1690
+ spec: graded ? r.spec : ((r.spec && (r.spec.min != null || r.spec.max != null)) ? { min: r.spec.min, max: r.spec.max } : null),
1691
+ conditions: r.series.map(se => se.condition), testDates: r.pointCount,
1692
+ outOfSpecNow: failing.length > 0, ...(failing.length ? { outOfSpecConditions: failing } : {}),
1693
+ shelfLife: first ? { condition: first.condition, fromT0Months: first.shelfLife.fromT0Months, ci95FromT0Months: first.shelfLife.ci95FromT0Months,
1694
+ verdict: first.shelfLife.verdict, headingToward: first.shelfLife.headingToward } : null,
1695
+ _t: first ? first.shelfLife._pointTotal : Infinity,
1696
+ });
1697
+ }
1698
+ if (!rows.length) return { error: `No dated measurements on ${entity.uid || entity.id}.` };
1699
+ rows.sort((a, b) => (b.outOfSpecNow - a.outOfSpecNow) || (a._t - b._t));
1700
+ const ranked = rows.filter(r => r.shelfLife).sort((a, b) => a._t - b._t);
1701
+ const formula = entityType === 'formulation' ? entity
1702
+ : (db.formulations || []).find(f => f.id === (entity.formulationId || ((db.batches || []).find(b => b.id === entity.batchId) || {}).formulationId)) || null;
1703
+ const ownT = formula ? parseFloat(formula.shelfLifeMonths) : NaN, defT = parseFloat(db.defaultShelfLifeMonths);
1704
+ const target = (Number.isFinite(ownT) && ownT > 0) ? { months: ownT, source: 'formula' }
1705
+ : (Number.isFinite(defT) && defT > 0) ? { months: defT, source: 'workspace default' } : null;
1706
+ return {
1707
+ entity: { type: entityType, uid: entity.uid, name: entity.name || entity.uid },
1708
+ allParameters: true,
1709
+ outOfSpecNow: rows.filter(r => r.outOfSpecNow).map(r => r.parameter),
1710
+ limitingParameter: ranked.length ? { parameter: ranked[0].parameter, ...ranked[0].shelfLife } : null,
1711
+ then: ranked.slice(1, 3).map(r => ({ parameter: r.parameter, condition: r.shelfLife.condition, fromT0Months: r.shelfLife.fromT0Months })),
1712
+ targetShelfLife: target,
1713
+ parameters: rows.map(({ _t, ...r }) => r),
1714
+ note: 'Every parameter the entity was tested for, as the app\'s All parameters plot: each judged on its own spec, out of spec now first (the latest test date of any condition failed), then by months to spec. shelfLife = the earliest-crossing condition\'s projection from T0 (point estimate and 95% bound, verdict against targetShelfLife), null = no reportable projection or a ranked / text parameter (those have no regression). limitingParameter = the first to cross spec: it sets the shelf life; then = the next two. For one parameter\'s full analysis (series, drift, control chart, time points, Arrhenius) call get_stability with that parameter.',
1715
+ };
1716
+ }
1717
+
1666
1718
  const get_stability = {
1667
1719
  definition: {
1668
1720
  name: 'get_stability',
1669
- 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. A point is one TEST DATE: every reading taken that day under that condition is averaged (points = test dates, readings = the raw count), so replicates never count as separate time points in the drift, control chart or shelf-life fit — the same points as the app. A ranked-scale (ordinal, e.g. pencil hardness) or text (e.g. appearance) parameter returns kind "ordinal" / "categorical" instead: per-condition points with the label (median rank for an ordinal), pass/fail, firstFail, latest and scaleShift — the app\'s step / pass-fail-strip trend, with no regression. Also returns timePoints (the app\'s Time points plot: per condition, what was tested at each time point, skipped pulls, the next pull with its due date and whether it is overdue, on the formula\'s own pull schedule or the standard one) and arrhenius (the app\'s Arrhenius plot: rates at the storage temperatures fitted to predict the rate and shelf life at predict_at_c, with 95% CIs and a verdict against the target shelf life). Use these figures directly; do not re-derive the regression.',
1721
+ 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. A point is one TEST DATE: every reading taken that day under that condition is averaged (points = test dates, readings = the raw count), so replicates never count as separate time points in the drift, control chart or shelf-life fit — the same points as the app. A ranked-scale (ordinal, e.g. pencil hardness) or text (e.g. appearance) parameter returns kind "ordinal" / "categorical" instead: per-condition points with the label (median rank for an ordinal), pass/fail, firstFail, latest and scaleShift — the app\'s step / pass-fail-strip trend, with no regression. Also returns timePoints (the app\'s Time points plot: per condition, what was tested at each time point, skipped pulls, the next pull with its due date and whether it is overdue, on the formula\'s own pull schedule or the standard one) and arrhenius (the app\'s Arrhenius plot: rates at the storage temperatures fitted to predict the rate and shelf life at predict_at_c, with 95% CIs and a verdict against the target shelf life). Without a parameter it returns every parameter at once (the app\'s All parameters plot): out of spec now first, then by months to spec, and limitingParameter, the one that crosses spec first and so sets the shelf life. Use these figures directly; do not re-derive the regression.',
1670
1722
  inputSchema: {
1671
1723
  type: 'object',
1672
1724
  properties: {
1673
1725
  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.' },
1674
- parameter: { type: 'string', description: 'The measured parameter to analyze (case-insensitive, e.g. "Niacinamide assay").' },
1726
+ parameter: { type: 'string', description: 'The measured parameter to analyze (case-insensitive, e.g. "Niacinamide assay"). Leave it out for every parameter at once: each one\'s spec status and months to spec, and the parameter that limits shelf life.' },
1675
1727
  by_condition: { type: 'boolean', description: 'Split the series by captured storage condition (default true). Set false to pool all conditions into one trend.' },
1676
1728
  predict_at_c: { type: 'number', description: 'Arrhenius: the storage temperature (°C) to predict the rate and shelf life at (default 25; the app offers 5, 25 and 30).' },
1677
1729
  order: { type: 'string', enum: ['zero', 'first'], description: 'Arrhenius kinetics: "zero" (a steady change per month, default) or "first" (a steady % change per month, e.g. an assay or viscosity falling by a share of what is left). meanR2ByOrder compares the two.' },
1678
1730
  as_of: { type: 'string', description: 'Date (YYYY-MM-DD) that time points\' next pulls are counted from (due in / overdue). Default today.' },
1679
1731
  },
1680
- required: ['entity_id', 'parameter'],
1732
+ required: ['entity_id'],
1681
1733
  },
1682
1734
  },
1683
1735
  handler: async (args) => {
@@ -1693,7 +1745,7 @@ const get_stability = {
1693
1745
  : new Set((db.samples || []).filter(s => (entityType === 'batch' ? s.batchId : s.formulationId) === entity.id).map(s => s.id));
1694
1746
 
1695
1747
  const paramLc = (args.parameter || '').trim().toLowerCase();
1696
- if (!paramLc) return { error: 'parameter is required.' };
1748
+ if (!paramLc) return _mcpAllParameters(entity, entityType, sampleIds, args, db);
1697
1749
  const points = [];
1698
1750
  const skipped = { ordinal: 0, categorical: 0 };
1699
1751
  const graded = []; // ordinal / text readings, for the step / strip trend (12w)
@@ -1788,6 +1840,7 @@ const get_stability = {
1788
1840
  const ys = pts.map(p => p.value);
1789
1841
  const n = ys.length;
1790
1842
  const out = { points: n, readings: pts.reduce((a, p) => a + (p.readings || 1), 0), 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) };
1843
+ Object.defineProperty(out, '_latestFail', { value: pts[n - 1].pf === 'fail' });
1791
1844
  if (n < 2) { out.note = 'Fewer than 2 points — no trend/shelf-life.'; return out; }
1792
1845
  // Drift on real elapsed months (not point order), like the shelf-life
1793
1846
  // projection and the app's Stability view: uneven ICH schedules
@@ -1826,17 +1879,21 @@ const get_stability = {
1826
1879
  overdue: as ? as.overdue : false,
1827
1880
  reportable: !!as,
1828
1881
  };
1882
+ // For the all-parameters ranking: the unrounded months from T0, and whether the latest test date failed.
1883
+ if (out.shelfLife && as) Object.defineProperty(out.shelfLife, '_pointTotal', { value: as.pointTotal });
1829
1884
  return out;
1830
1885
  };
1831
1886
 
1887
+ // A spread drops analyze's non-enumerable _latestFail (for the all-parameters ranking): carry it over.
1888
+ const withCond = (condition, pts) => { const a = analyze(pts); return Object.defineProperty({ condition, ...a }, '_latestFail', { value: a._latestFail }); };
1832
1889
  const split = args.by_condition !== false && points.some(p => p.cond);
1833
1890
  let series;
1834
1891
  if (split) {
1835
1892
  const byC = new Map();
1836
1893
  points.forEach(p => { const k = p.cond || '(no condition)'; if (!byC.has(k)) byC.set(k, []); byC.get(k).push(p); });
1837
- series = [...byC.keys()].sort().map(k => ({ condition: k, ...analyze(byC.get(k)) }));
1894
+ series = [...byC.keys()].sort().map(k => withCond(k, byC.get(k)));
1838
1895
  } else {
1839
- series = [{ condition: null, ...analyze(points) }];
1896
+ series = [withCond(null, points)];
1840
1897
  }
1841
1898
 
1842
1899
  return {