formlab-mcp 0.6.10 → 0.6.12

package/README.md

@@ -29,22 +29,23 @@ Ask Claude (or another MCP client) things like:
 | Tool | Purpose |
 |---|---|
 | `list_formulations` | Filtered list of recipes |
-| `get_formulation` | Full record + flattened wt-% composition (sub-formulas expanded) |
+| `get_formulation` | Full record + flattened wt-% composition (sub-formulas expanded), the ordered **step procedure**, user **custom fields**, and any **process-factor values** (DOE inputs — cure temp, mix time, RPM, pH…) |
 | `find_similar_formulations` | Find formulas using a given ingredient ≥ threshold % |
 | `compare_formulations` | Pairwise side-by-side composition diff |
 | `list_ingredients` | Filtered list of raw materials. Filters: `family`, `supplier`, `name_contains`, `in_stock_only`, `ingredient_class` (small-molecule / surfactant / polymer / extract / fragrance / pigment / sequence / mixture), `sequence_contains` (e.g. `KTTKS` → Matrixyl), `taxon_contains` (e.g. `Centella`) |
-| `get_ingredient` | Full record + supplier / **cost ($/kg)** / stock / formulations using it, plus **GHS safety** (pictograms, H/P codes, signal word), **per-jurisdiction regulatory status**, and **inventory lots** (balances + expiry). Returns every class-specific sub-object when present: `sequence` (peptide / oligo), `taxon` (NCBI ID + scientific name), `ingredientClass`, `extractDetails`, `sequenceDetails`, `polymerDetails`, `surfactantDetails`, `pigmentDetails`, `fragranceDetails` |
+| `get_ingredient` | Full record + supplier / **cost ($/kg)** / stock / chemical name / molecular weight / storage / formulations using it, plus **GHS safety** (pictograms, H/P codes, signal word), **per-jurisdiction regulatory status**, and **inventory lots** (balances + expiry). Returns every class-specific sub-object when present: `sequence` (peptide / oligo), `taxon` (NCBI ID + scientific name), `ingredientClass`, `extractDetails`, `sequenceDetails`, `polymerDetails`, `surfactantDetails`, `pigmentDetails`, `fragranceDetails` |
 | `list_lots` | Inventory lots across ingredients (each a received batch with its own remaining balance, supplier, expiry). Filters: `ingredient_id`, `expiring_within_days`, `status` |
 | `list_inventory` | Portfolio stock rollup — one row per ingredient with on-hand qty, summed lot balance, nearest expiry, and a low-stock flag (on-hand ≤ `reorderThreshold`, or zero). Filters: `low_stock_only`, `expiring_within_days`, `family` |
 | `list_batches` | Filtered list of production / lab-prep events |
-| `get_batch` | Full record + actual composition + samples + blend lineage |
+| `get_batch` | Full record + actual composition, measured/derived **actual volume** (mass ÷ density, never a sum of per-ingredient volumes), the **process** method + any **process-factor values** (DOE inputs), samples + blend lineage |
 | `list_samples` | Filtered list of physical specimens |
 | `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, and the **resolved instrument** (`instrumentSource`: row / method / run) |
+| `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 |
 | `get_doe_matrix` | Pivot matrix (CSV by default) — rows × ingredients × parameters |
 | `find_failures` | Pareto-style: parameters that fail acceptance most often |
 | `get_coverage_matrix` | Which formulations × parameters have been measured (TEST coverage) |
+| `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), split by storage condition |
 | `get_design_space` | COMPOSITION design space for one project: 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. Matches the in-app Design Space Viewer exactly. Answers *"where haven't I explored?"* / *"what should I formulate next?"* |
 | `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` |
 | `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 |
@@ -137,7 +138,7 @@ Or for local-dev (from the repo):
     "formlab": {
       "command": "node",
       "args": [
-        "/Users/you/Documents/GitHub/formlab/mcp/index.js",
+        "/Users/you/formlab/mcp/index.js",
         "/Users/you/Downloads/formlab-export-2026-05-30.json"
       ]
     }

package/SUBMISSION.md

@@ -47,7 +47,7 @@ _"what parameters fail acceptance most often?"_, or _"show me the DOE matrix
 at sample grain for Anti-Aging Serum family"_ — all against a JSON export
 that stays on the user's laptop.
 
-**33 read-only tools** covering formulations, ingredients, batches, samples,
+**34 read-only tools** covering formulations, ingredients, batches, samples,
 test results, DOE matrices + saved designs, similarity, failure analysis,
 test-coverage AND composition design-space mapping (varying ingredients,
 untested gaps, PCA), equipment, test methods, panels, projects and ELN notes.
@@ -100,13 +100,13 @@ Already written to `mcp/server.json` in this repo. Uses:
 - Namespace: `io.github.juliu1980/formlab-mcp` (GitHub OAuth proves ownership)
 - Status: `active`
 - Repository: `https://github.com/juliu1980/FormLab` with subfolder `mcp`
-- Version: pulled from `package.json` (currently `0.1.1`)
+- Version: pulled from `package.json` (currently `0.6.12`)
 - Package: npm `formlab-mcp` with stdio transport + positional `exportPath` arg
 
 ### Publish (the OAuth step is interactive)
 
 ```bash
-cd /Users/juliu/Documents/GitHub/formlab/mcp
+cd ~/GitHub/formlab/mcp
 mcp-publisher login        # opens GitHub OAuth in your browser as juliu1980
 mcp-publisher publish      # reads server.json and submits
 ```

package/package.json

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

package/tools/analytics.js

@@ -59,15 +59,57 @@ function _trimTest(t, samplesById) {
   };
 }
 
+// Aggregate a time series by timestamp — the read-only mirror of the app's
+// _tsAggregateByT. Any t appearing 2+ times is a set of POINT replicates
+// (repeat readings at that timestamp), averaged to mean ± sd. One entry per
+// distinct t, sorted by t. A series with no duplicate t aggregates to itself.
+function _mcpTsAggregate(points) {
+  const groups = new Map();
+  for (const p of (Array.isArray(points) ? points : [])) {
+    const t = parseFloat(p && (p.t ?? p.x));
+    const v = parseFloat(p && (p.value ?? p.y));
+    if (!Number.isFinite(t) || !Number.isFinite(v)) continue;
+    if (!groups.has(t)) groups.set(t, []);
+    groups.get(t).push(v);
+  }
+  const out = [];
+  [...groups.keys()].sort((a, b) => a - b).forEach(t => {
+    const vals = groups.get(t); const n = vals.length;
+    const mean = vals.reduce((a, b) => a + b, 0) / n;
+    const sd = n >= 2 ? Math.sqrt(vals.reduce((a, b) => a + (b - mean) ** 2, 0) / (n - 1)) : 0;
+    out.push({ t: _round(t, 6), n, mean: _round(mean, 6), sd: _round(sd, 6) });
+  });
+  return out;
+}
+
 function _trimMeasurement(m, t, db) {
   const ins = _resolveInstrument(m, t, db);
+  const type = m.type || 'scalar';
+  // Reduce a complex type to the single representative every analysis surface
+  // uses (time_series → final point, distribution → D50), and — for a series —
+  // expose per-timestamp aggregation so an agent can see POINT replicates
+  // (repeat readings at one t) as mean ± sd. This is DISTINCT from SERIES
+  // replicates (the same parameter measured as separate measurement rows in the
+  // report); see the report-level `seriesReplicates` on get_test_result.
+  const complex = {};
+  if (type === 'time_series' && Array.isArray(m.points) && m.points.length) {
+    const agg = _mcpTsAggregate(m.points);
+    complex.aggregated = agg;                                  // [{t,n,mean,sd}]
+    complex.pointReplicates = agg.some(g => g.n >= 2);         // any t with n≥2
+    const last = agg[agg.length - 1];
+    complex.representative = last ? { value: last.mean, basis: 'final' } : null;
+  } else if (type === 'distribution' && Array.isArray(m.bins) && m.bins.length) {
+    const d50 = m.bins.find(b => String(b.label || '').toUpperCase().replace(/\s/g, '') === 'D50');
+    complex.representative = d50 ? { value: _round(parseFloat(d50.value), 6), basis: 'D50' } : null;
+  }
   return {
     parameter: m.parameter || '',
     value: m.value ?? null,
     unit: m.unit || '',
-    type: m.type || 'scalar',
+    type,
     pointCount: Array.isArray(m.points) ? m.points.length : 0,
     binCount: Array.isArray(m.bins) ? m.bins.length : 0,
+    ...complex,
     acceptanceCriteria: m.acceptanceCriteria || null,
     // Captured run conditions this reading was measured under (e.g.
     // {Storage: "40 °C / 75% RH"}, {RPM: "50"}) — the condition travels with the
@@ -141,7 +183,7 @@ const list_test_results = {
 const get_test_result = {
   definition: {
     name: 'get_test_result',
-    description: 'Get full details for a single test result report: every measurement\'s value, unit, type, acceptance criteria, captured run CONDITIONS (e.g. {Storage:"40 °C / 75% RH"} — the storage/temp/RPM the reading was measured under, so it is self-describing and comparable across runs; present only when captured), and the INSTRUMENT that produced it. instrument is RESOLVED (measurement override → the parameter\'s Test Method equipment → the report default) with instrumentSource telling you which — treat source "run" as an inherited assumption, not evidence. Accepts internal id or UID.',
+    description: 'Get full details for a single test result report: every measurement\'s value, unit, type, acceptance criteria, captured run CONDITIONS (e.g. {Storage:"40 °C / 75% RH"} — the storage/temp/RPM the reading was measured under, so it is self-describing and comparable across runs; present only when captured), and the INSTRUMENT that produced it. instrument is RESOLVED (measurement override → the parameter\'s Test Method equipment → the report default) with instrumentSource telling you which — treat source "run" as an inherited assumption, not evidence. For complex measurements a `representative` value is included (time_series → final point, distribution → D50); a time_series also carries `aggregated` (per-timestamp mean ± sd) and `pointReplicates` (true when a timestamp has repeat readings — POINT replicates, averaged per t). The report-level `seriesReplicates` lists parameters measured 2+ times as SEPARATE rows (SERIES replicates). These two notions are different: point replicates are within one run, series replicates are repeated runs. Accepts internal id or UID.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -154,9 +196,25 @@ const get_test_result = {
     const { indexes } = getStore();
     const t = resolveById('testResults', args.id);
     if (!t) return { error: `No test result found for id "${args.id}".` };
+    // SERIES replicates: a parameter measured 2+ times in THIS report as separate
+    // measurement rows (grouped by parameter+method+unit). Distinct from POINT
+    // replicates, which are repeat readings at one timestamp WITHIN a single
+    // time-series measurement (see each measurement's `pointReplicates`).
+    const _repCount = new Map();
+    (t.measurements || []).forEach(m => {
+      const k = `${(m.parameter || '').trim().toLowerCase()}|${(m.method || '').trim().toLowerCase()}|${(m.unit || '').trim().toLowerCase()}`;
+      _repCount.set(k, (_repCount.get(k) || 0) + 1);
+    });
+    const seriesReplicates = (t.measurements || [])
+      .filter((m, i, arr) => arr.findIndex(x => (x.parameter || '') === (m.parameter || '') && (x.method || '') === (m.method || '') && (x.unit || '') === (m.unit || '')) === i)
+      .map(m => ({ parameter: m.parameter || '', n: _repCount.get(`${(m.parameter || '').trim().toLowerCase()}|${(m.method || '').trim().toLowerCase()}|${(m.unit || '').trim().toLowerCase()}`) || 1 }))
+      .filter(r => r.n >= 2);
     return {
       ..._trimTest(t, indexes.samplesById),
       notes: t.notes || '',
+      // Parameters measured 2+ times as separate rows (series replicates). Empty
+      // when none. Point replicates live on each measurement (`pointReplicates`).
+      seriesReplicates,
       measurements: (t.measurements || []).map(m => _trimMeasurement(m, t, getStore().db)),
     };
   },

package/tools/lab.js

@@ -69,6 +69,9 @@ function _trimBatch(b, formulationsById) {
     preparedDate: b.preparedDate || '',
     preparedBy: b.preparedBy || '',
     process: b.process || '',
+    // Per-batch process-factor values (DOE Matrix "+ Factor" at batch grain) —
+    // recorded process conditions (cure temp, mix time, RPM, pH, …) as DOE INPUTS.
+    processFactors: (b.processFactors || []).filter(x => x && x.name).map(x => ({ name: x.name, value: x.value != null ? x.value : '', unit: x.unit || '' })),
     parentBatchId: b.parentBatchId || null,
     isBlend: Array.isArray(b.sourceBlend) && b.sourceBlend.length > 0,
     blendParentCount: Array.isArray(b.sourceBlend) ? b.sourceBlend.length : 0,