formlab-mcp 0.6.68 → 0.6.70
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 +2 -2
- package/package.json +1 -1
- package/server.json +2 -2
- package/tools/analytics.js +43 -8
- package/tools/lab.js +6 -1
package/README.md
CHANGED
|
@@ -42,7 +42,7 @@ Ask Claude (or another MCP client) things like:
|
|
|
42
42
|
| `list_batches` | Filtered list of production / lab-prep events |
|
|
43
43
|
| `get_batch` | Full record + actual composition, measured/derived **actual volume** (mass ÷ density, never a sum of per-ingredient volumes) and **actual mass** (yield, else summed as-prepared inputs — mL rows through that ingredient's density — else measured volume × density), **estimatedVolume** (mass ÷ the formula's finished density when no actual exists, flagged `estimate: true`), **plannedMass** for volume-target batches (target × finished density) and **formulaFinishedDensity**, the **process** method + any **process-factor values** (DOE inputs), samples + blend lineage, and — as a finished-goods lot — its storage **`location`** + finished-goods **`stockLedger`** (shipments out + adjustments; `shippedQty` total), and its **theoretical parameters computed on the batch as made** (actual composition when logged — `basis: "actual"` — else the recipe; the batch's own parameter list when it overrides the formula's) |
|
|
44
44
|
| `list_samples` | Filtered list of physical specimens |
|
|
45
|
-
| `get_sample` | Full record + canonical variant + test reports + blend lineage |
|
|
45
|
+
| `get_sample` | Full record + canonical variant + test reports + blend lineage + its stability pulls (next pull, or pulled at) |
|
|
46
46
|
| `list_test_results` | Filtered list of test reports (by sample, parameter, **measured-value range** (`value_min`/`value_max` — a curve at its final point, a distribution at its spec's statistic or D50), **grade** (`min_grade`/`max_grade` on a ranked scale), **text value** (`value_equals`), **run condition** (`condition`), date, or lab) |
|
|
47
47
|
| `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 distribution also its `bins` and, when its spec names a statistic, `judged` at it); a ranked grade carries its `scale` and `rank`; 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 |
|
|
48
48
|
| `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 |
|
|
@@ -53,7 +53,7 @@ Ask Claude (or another MCP client) things like:
|
|
|
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
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
|
-
| `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 |
|
|
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 and every pull still ahead (`ahead`, as the app's Calendar); 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` |
|
|
59
59
|
| `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 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "formlab-mcp",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.70",
|
|
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.
|
|
5
|
+
"version": "0.6.70",
|
|
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.
|
|
11
|
+
"version": "0.6.70",
|
|
12
12
|
"runtimeHint": "npx",
|
|
13
13
|
"transport": {
|
|
14
14
|
"type": "stdio"
|
package/tools/analytics.js
CHANGED
|
@@ -1511,7 +1511,9 @@ function _mcpStorageCond(m) {
|
|
|
1511
1511
|
}
|
|
1512
1512
|
return '';
|
|
1513
1513
|
}
|
|
1514
|
-
|
|
1514
|
+
// perSample (a Map) also gets each sample's pulls, as the app's formula page reads them (stabNextPullsBySample): sid →
|
|
1515
|
+
// [{ condition, ...next, schedule, pulledAt }], a sample tested at one time point past T₀ being the container pulled.
|
|
1516
|
+
function _mcpPullsDue(db, now, perSample) {
|
|
1515
1517
|
const due = [], stopped = [];
|
|
1516
1518
|
const explore = _mcpExplorationIds(db);
|
|
1517
1519
|
const defT = parseFloat(db.defaultShelfLifeMonths);
|
|
@@ -1531,15 +1533,30 @@ function _mcpPullsDue(db, now) {
|
|
|
1531
1533
|
(t.measurements || []).forEach(m => {
|
|
1532
1534
|
const cond = _mcpStorageCond(m).trim();
|
|
1533
1535
|
if (!cond) return;
|
|
1534
|
-
if (!byCond.has(cond)) { byCond.set(cond, new Map()); condSamples.set(cond, new
|
|
1536
|
+
if (!byCond.has(cond)) { byCond.set(cond, new Map()); condSamples.set(cond, new Map()); }
|
|
1535
1537
|
byCond.get(cond).set(day, ms);
|
|
1536
|
-
condSamples.get(cond)
|
|
1538
|
+
const cs = condSamples.get(cond); // the containers stored under it, with their test days
|
|
1539
|
+
if (!cs.has(sid)) cs.set(sid, new Set());
|
|
1540
|
+
cs.get(sid).add(ms);
|
|
1537
1541
|
const p = String(m.parameter || '').trim(); if (p) params.set(p, (params.get(p) || 0) + 1);
|
|
1538
1542
|
});
|
|
1539
1543
|
}));
|
|
1540
1544
|
const conds = [...byCond.entries()].filter(([, d]) => d.size >= 2);
|
|
1541
1545
|
if (!conds.length) return;
|
|
1542
1546
|
const t0 = Math.min(...conds.flatMap(([, d]) => [...d.values()]));
|
|
1547
|
+
// A container in a chamber and not tested yet joins the study its storageLocation names (the app's 48v rule): the
|
|
1548
|
+
// same temperature, and a humidity it names picks between two.
|
|
1549
|
+
sids.forEach(sid => {
|
|
1550
|
+
if (testsOf.has(sid) || !live.has(sid)) return;
|
|
1551
|
+
const x = (db.samples || []).find(y => y && y.id === sid), loc = String((x && x.storageLocation) || '');
|
|
1552
|
+
const tC = loc ? _condTempC(loc) : null;
|
|
1553
|
+
if (tC == null) return;
|
|
1554
|
+
const at = conds.filter(([c]) => _condTempC(c) === tC);
|
|
1555
|
+
if (!at.length) return;
|
|
1556
|
+
const rh = (loc.match(/\/\s*(\d{2,3})|(\d{2,3})\s*%/) || []).slice(1).find(Boolean);
|
|
1557
|
+
const [cond] = (rh && at.find(([c]) => new RegExp(`(^|\\D)${rh}(\\D|$)`).test(c.replace(/-?\d+(?:\.\d+)?\s*°/, '')))) || at[0];
|
|
1558
|
+
condSamples.get(cond).set(sid, new Set());
|
|
1559
|
+
});
|
|
1543
1560
|
const ownT = parseFloat(f.shelfLifeMonths);
|
|
1544
1561
|
const target = ownT > 0 ? ownT : defT > 0 ? defT : null;
|
|
1545
1562
|
const plan = _tpPlanOf(f);
|
|
@@ -1548,13 +1565,23 @@ function _mcpPullsDue(db, now) {
|
|
|
1548
1565
|
const tC = _condTempC(cond);
|
|
1549
1566
|
const r = _tpCond([...d.values()].map(ms => ({ date: new Date(ms) })), t0, tC, target, plan, now);
|
|
1550
1567
|
if (!r.next) return;
|
|
1551
|
-
const sampleIds = [...condSamples.get(cond)].filter(id => live.has(id));
|
|
1568
|
+
const sampleIds = [...condSamples.get(cond).keys()].filter(id => live.has(id));
|
|
1552
1569
|
if (!sampleIds.length) return; // every sample under it discarded: the study is over there
|
|
1553
1570
|
const last = r.cells.get(r.lastKey);
|
|
1571
|
+
// Every pull still ahead on this schedule, the next and each one after it: the app's pull calendar (47k).
|
|
1572
|
+
const ahead = _tpLadder(tC, target, plan).filter(e => _tpBucket(_pullDays(e), r.weekDays).key > r.lastKey)
|
|
1573
|
+
.map(e => { const due = t0 + _pullDays(e) * _MS_PER_DAY; return _nextOut({ label: _pullLabel(e), due: new Date(due), days: Math.floor((due - now) / _MS_PER_DAY) }); });
|
|
1554
1574
|
const row = { formula: { id: f.id, uid: f.uid || null, name: f.name || f.uid || 'Formula' }, condition: cond, temperatureC: _round(tC, 1),
|
|
1555
|
-
schedule: r.own ? 'formula' : 'standard', t0: _dayOf(t0), lastTimePoint: last ? last.label : null, ..._nextOut(r.next), parameter: param,
|
|
1575
|
+
schedule: r.own ? 'formula' : 'standard', t0: _dayOf(t0), lastTimePoint: last ? last.label : null, ..._nextOut(r.next), parameter: param, ahead,
|
|
1556
1576
|
samples: sampleIds.map(id => { const x = (db.samples || []).find(y => y && y.id === id); return x ? (x.uid || x.id) : id; }) };
|
|
1557
1577
|
(r.next.days < -_PULL_STALE_D ? stopped : due).push(row);
|
|
1578
|
+
if (perSample && r.next.days >= -_PULL_STALE_D) sampleIds.forEach(id => {
|
|
1579
|
+
const keys = new Map();
|
|
1580
|
+
condSamples.get(cond).get(id).forEach(ms => { if (ms <= now + _MS_PER_DAY) { const b = _tpBucket((ms - t0) / _MS_PER_DAY, r.weekDays); keys.set(b.key, b.label); } });
|
|
1581
|
+
const pts = [...keys.entries()].sort((a, b) => a[0] - b[0]);
|
|
1582
|
+
if (!perSample.has(id)) perSample.set(id, []);
|
|
1583
|
+
perSample.get(id).push({ condition: cond, ..._nextOut(r.next), schedule: row.schedule, pulledAt: pts.length === 1 && pts[0][0] > 0 ? pts[0][1] : null });
|
|
1584
|
+
});
|
|
1558
1585
|
});
|
|
1559
1586
|
});
|
|
1560
1587
|
const byDays = (a, b) => a.daysUntil - b.daysUntil;
|
|
@@ -1913,7 +1940,7 @@ const get_stability = {
|
|
|
1913
1940
|
const list_stability_pulls = {
|
|
1914
1941
|
definition: {
|
|
1915
1942
|
name: 'list_stability_pulls',
|
|
1916
|
-
description: 'Stability pulls due across the whole workspace: the app\'s Needs Attention "stability pulls due" row, without naming a formula. Every formula on a stability study (tests under a storage condition with a temperature in its name, on 2+ dates) gives its next pull per condition, on the formula\'s own pull schedule or the standard one (1, 2, 3, 6 months at 35 °C and up; 1, 2, 3, 6, 9, 12, 18, 24, 36 months up to the target shelf life). A test of ANY parameter in a time point under that condition counts as the pull; T0 is the formula\'s first such test. Returns the pulls overdue or due within within_days (default 7), soonest first, with formula, condition, time point, due date, daysUntil (negative = overdue), schedule, the last time point tested, the parameter the study measures most, and the samples to pull (UIDs; discarded ones left out, and a condition whose samples are all discarded has nothing due). Only the storage part of a reading\'s conditions counts (a measurement temperature such as Temperature 25 °C does not make a study); ICH shorthand such as 40/75 reads as 40 °C; a test dated after as_of does not count as pulled yet. A pull more than 60 days late is a study that stopped: listed apart under stopped. Exploration runs (DOE / screening), archived and trashed formulas are left out, as in the app. For one formula\'s full time-point grid use get_stability (timePoints).',
|
|
1943
|
+
description: 'Stability pulls due across the whole workspace: the app\'s Needs Attention "stability pulls due" row, without naming a formula. Every formula on a stability study (tests under a storage condition with a temperature in its name, on 2+ dates) gives its next pull per condition, on the formula\'s own pull schedule or the standard one (1, 2, 3, 6 months at 35 °C and up; 1, 2, 3, 6, 9, 12, 18, 24, 36 months up to the target shelf life). A test of ANY parameter in a time point under that condition counts as the pull; T0 is the formula\'s first such test. Returns the pulls overdue or due within within_days (default 7), soonest first, with formula, condition, time point, due date, daysUntil (negative = overdue), schedule, the last time point tested, the parameter the study measures most, ahead (every pull still ahead on that schedule, the next first, each with its due date and daysUntil: what the app\'s Calendar button exports), and the samples to pull (UIDs; discarded ones left out, and a condition whose samples are all discarded has nothing due). Only the storage part of a reading\'s conditions counts (a measurement temperature such as Temperature 25 °C does not make a study); ICH shorthand such as 40/75 reads as 40 °C; a test dated after as_of does not count as pulled yet. A pull more than 60 days late is a study that stopped: listed apart under stopped. Exploration runs (DOE / screening), archived and trashed formulas are left out, as in the app. For one formula\'s full time-point grid use get_stability (timePoints).',
|
|
1917
1944
|
inputSchema: {
|
|
1918
1945
|
type: 'object',
|
|
1919
1946
|
properties: {
|
|
@@ -1941,12 +1968,20 @@ const list_stability_pulls = {
|
|
|
1941
1968
|
count: pulls.length, overdue: pulls.filter(x => x.overdue).length, pulls,
|
|
1942
1969
|
later: r.due.filter(x => mine(x) && x.daysUntil > within).length,
|
|
1943
1970
|
stopped: r.stopped.filter(mine),
|
|
1944
|
-
note: 'daysUntil < 0 = overdue by that many days. schedule "formula" = the formula\'s own pulls, else "standard". later = studies whose next pull is further out than within_days. stopped = next pull more than 60 days late, read as a study that ended; the app leaves these out of Needs Attention. Narrate these figures; do not recompute the schedule.',
|
|
1971
|
+
note: 'daysUntil < 0 = overdue by that many days. schedule "formula" = the formula\'s own pulls, else "standard". later = studies whose next pull is further out than within_days (within_days 3650 lists every study). ahead = the rest of each row\'s schedule, the next pull first: for "what is coming up" over months, read ahead rather than recomputing from the schedule. stopped = next pull more than 60 days late, read as a study that ended; the app leaves these out of Needs Attention. Narrate these figures; do not recompute the schedule.',
|
|
1945
1972
|
};
|
|
1946
1973
|
},
|
|
1947
1974
|
};
|
|
1948
1975
|
|
|
1949
|
-
|
|
1976
|
+
// One sample's pulls (get_sample): its studies' next pulls, soonest first, a container already pulled last.
|
|
1977
|
+
function _mcpSamplePulls(db, sample, now) {
|
|
1978
|
+
const per = new Map();
|
|
1979
|
+
const { due } = _mcpPullsDue(db, now, per);
|
|
1980
|
+
return { list: (per.get(sample.id) || []).sort((a, b) => (!!a.pulledAt - !!b.pulledAt) || a.daysUntil - b.daysUntil),
|
|
1981
|
+
formulaOnStudy: due.some(x => x.formula.id === sample.formulationId) };
|
|
1982
|
+
}
|
|
1983
|
+
|
|
1984
|
+
export { _mcpSamplePulls, _mcpRepNumber, _mcpMeasType, _evalPassFail, _resolveSpec, _shelfLife, _shelfLifeAssess, _mcpCondTags, _mcpArmNames, _mcpCondDefaultScore, _mcpCondSig, _mcpCondLabel, _mcpParamGroupsOf };
|
|
1950
1985
|
// ============================================================
|
|
1951
1986
|
// compare_test_results — the app's Compare Results table (js/views/testing-
|
|
1952
1987
|
// compare.js), 13g. Items are formulas, batches, samples or test reports; each
|
package/tools/lab.js
CHANGED
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
import { getStore, resolveById } from '../data.js';
|
|
10
10
|
import { theoreticalParams } from '../theoretical.js';
|
|
11
|
+
import { _mcpSamplePulls } from './analytics.js';
|
|
11
12
|
|
|
12
13
|
// --- Self-contained unit conversion + actual-volume derivation ---------------
|
|
13
14
|
// The MCP server has no access to the app's cost.js helpers, so a small local
|
|
@@ -350,11 +351,12 @@ const list_samples = {
|
|
|
350
351
|
const get_sample = {
|
|
351
352
|
definition: {
|
|
352
353
|
name: 'get_sample',
|
|
353
|
-
description: 'Get full details for a single sample including its actual variant composition, all test results bound to it, blend lineage, and
|
|
354
|
+
description: 'Get full details for a single sample including its actual variant composition, all test results bound to it, blend lineage, storage info, and its stability pulls (the formula page\'s Next pull column): stabilityPulls lists each study it is stored under with the next time point, due date, daysUntil (negative = overdue) and schedule, soonest first; pulledAt names the one time point a container tested once past T0 was pulled for (it is no longer in the study). A sample not tested yet joins the study its storageLocation names (e.g. "Chamber 40 °C", "25/60"). Accepts internal id or UID (e.g. SAMP-0001).',
|
|
354
355
|
inputSchema: {
|
|
355
356
|
type: 'object',
|
|
356
357
|
properties: {
|
|
357
358
|
id: { type: 'string', description: 'Internal id or UID of the sample.' },
|
|
359
|
+
as_of: { type: 'string', description: 'Date (YYYY-MM-DD) its stability pulls count from. Default today.' },
|
|
358
360
|
},
|
|
359
361
|
required: ['id'],
|
|
360
362
|
},
|
|
@@ -364,6 +366,7 @@ const get_sample = {
|
|
|
364
366
|
const s = resolveById('samples', args.id);
|
|
365
367
|
if (!s) return { error: `No sample found for id "${args.id}".` };
|
|
366
368
|
const tests = (db.testResults || []).filter(t => t.sampleId === s.id);
|
|
369
|
+
const pulls = _mcpSamplePulls(db, s, args.as_of && /^\d{4}-\d{2}-\d{2}$/.test(args.as_of) ? Date.parse(args.as_of) : Date.now());
|
|
367
370
|
const canonical = (s.actualVariants || []).find(v => v.isCanonical) || (s.actualVariants || [])[0] || null;
|
|
368
371
|
const parents = Array.isArray(s.sourceBlend)
|
|
369
372
|
? s.sourceBlend.map(p => {
|
|
@@ -386,6 +389,8 @@ const get_sample = {
|
|
|
386
389
|
compositionRowCount: Array.isArray(canonical.composition) ? canonical.composition.length : 0,
|
|
387
390
|
} : null,
|
|
388
391
|
sourceBlendParents: parents,
|
|
392
|
+
stabilityPulls: pulls.list,
|
|
393
|
+
...(!tests.length && !pulls.list.length && pulls.formulaOnStudy ? { stabilityPullsNote: 'Not tested yet, and its storageLocation names none of its formula\'s study chambers (e.g. "40 °C"), so it has no pulls.' } : {}),
|
|
389
394
|
testCount: tests.length,
|
|
390
395
|
tests: tests.map(t => ({
|
|
391
396
|
id: t.id,
|