formlab-mcp 0.6.23 → 0.6.24

package/README.md

@@ -29,7 +29,7 @@ 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), the ordered **step procedure**, user **custom fields**, and any **process-factor values** (DOE inputs — cure temp, mix time, RPM, pH…) |
+| `get_formulation` | Full record + flattened wt-% composition (sub-formulas expanded), the ordered **step procedure**, user **custom fields**, any **process-factor values** (DOE inputs — cure temp, mix time, RPM, pH…), and the declared **finishedDensity** (g/mL of the mixed product; volume-targeted batches scale by it) |
 | `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`) |
@@ -39,7 +39,7 @@ Ask Claude (or another MCP client) things like:
 | `get_supplier` | One supplier in full: record, every ingredient it's an approved source for, every lot from it, and the **recall trace** (batches that consumed those lots → products, shipments, samples, sub-batches; lots on hold flagged) |
 | `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, measured/derived **actual volume** (mass ÷ density, never a sum of per-ingredient volumes) and **actual mass** (yield, else summed inputs, else measured volume × density), 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) |
+| `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) |
 | `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) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.23",
+  "version": "0.6.24",
   "mcpName": "io.github.juliu1980/formlab-mcp",
   "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",

package/tools/formulations.js

@@ -23,6 +23,11 @@ function _trimFormulation(f) {
     owner: f.owner || '',
     regulatoryCategory: f.regulatoryCategory || '',
     shelfLifeMonths: f.shelfLifeMonths ?? null,
+    // Density of the MIXED product (g/mL), when declared — volume-targeted
+    // batches scale by it instead of the ideal-mix estimate. null = not set.
+    finishedDensity: (f.finishedDensity && isFinite(parseFloat(f.finishedDensity.value)))
+      ? { value: parseFloat(f.finishedDensity.value), temp: f.finishedDensity.temp ?? null, source: f.finishedDensity.source || 'manual', batchId: f.finishedDensity.batchId || null, date: f.finishedDensity.date || null }
+      : null,
     tags: f.tags || [],
     projectId: f.projectId || null,
     compositionRowCount: (f.composition || []).length,

package/tools/lab.js

@@ -25,16 +25,57 @@ function _batchUnitMassKg(b) {
   const v = parseFloat(b.unitMass.value);
   return (isFinite(v) && v > 0) ? _massToKg(v, b.unitMass.unit) : null;
 }
-function _batchActualMassKg(b) {
+// Ingredient density → kg/L (=== g/mL). Mirrors the app's _densityToKgPerL for
+// the units it accepts; unknown unit → treated as g/mL (the app's default).
+const _DENS_TO_KGL = { 'g/ml': 1, 'g/cm3': 1, 'g/cm³': 1, 'g/cc': 1, 'kg/l': 1, 'kg/m3': 0.001, 'kg/m³': 0.001, 'g/l': 0.001, 'lb/gal': 0.119826, 'lb/ft3': 0.0160185, 'lb/ft³': 0.0160185 };
+function _densKgPerL(v, u) { const d = parseFloat(v); if (!isFinite(d) || d <= 0) return null; const f = _DENS_TO_KGL[String(u || 'g/mL').trim().toLowerCase()]; return d * (f == null ? 1 : f); }
+// Density of ONE as-prepared row: the ingredient's own density, or a sub-
+// formula's declared finished density. null when unknown.
+function _rowDensityKgPerL(c, ingredientsById, formulationsById) {
+  if (c.ingredientId && ingredientsById) { const ing = ingredientsById.get(c.ingredientId); return ing ? _densKgPerL(ing.density, ing.densityUnit) : null; }
+  if (c.formulationId && formulationsById) { const sf = formulationsById.get(c.formulationId); return sf ? _formulaFinishedDensity(sf) : null; }
+  return null;
+}
+// The formula's DECLARED finished density (g/mL) — adopted from a measured
+// batch or entered from a spec. The app also has an ideal-mix estimate from
+// ingredient densities; MCP does not reproduce that (estimate) and returns
+// null instead, so a null here means "the app plans with an estimate".
+function _formulaFinishedDensity(f) {
+  const v = f && f.finishedDensity ? parseFloat(f.finishedDensity.value) : NaN;
+  return (isFinite(v) && v > 0) ? v : null;
+}
+function _finishedDensityInfo(f, batchesById) {
+  const v = _formulaFinishedDensity(f);
+  if (v == null) return null;
+  const fd = f.finishedDensity;
+  const src = (fd.batchId && batchesById) ? batchesById.get(fd.batchId) : null;
+  return { value: v, unit: 'g/mL', temp: fd.temp ?? null, source: fd.source || 'manual', fromBatch: src ? src.uid : null, date: fd.date || null };
+}
+// Σ as-prepared row masses in kg, each row through ITS OWN unit: g rows
+// directly, mL rows × that ingredient's density. Mirrors sumActualRowsMassKg
+// in the app (cost.js). Any volume row that can't resolve → null (never a
+// partial sum that silently drops the water).
+function _sumActualRowsKg(rows, ingredientsById, formulationsById) {
+  if (!Array.isArray(rows)) return null;
+  let kg = 0, n = 0;
+  for (const c of rows) {
+    if (!c || !(c.ingredientId || c.formulationId)) continue;
+    const a = parseFloat(c.amount); if (!isFinite(a)) continue;
+    const m = _massToKg(a, c.unit); if (m != null) { kg += m; n++; continue; }
+    const L = _volToL(a, c.unit);
+    if (L != null) { const d = _rowDensityKgPerL(c, ingredientsById, formulationsById); if (d == null) return null; kg += L * d; n++; }
+  }
+  return n ? kg : null;
+}
+function _batchActualMassKg(b, ingredientsById, formulationsById) {
   const y = parseFloat(b.actualYield);
   if (isFinite(y)) {
     const kg = _massToKg(y, b.unit); if (kg != null) return kg;
     const umk = _batchUnitMassKg(b); if (umk != null) return y * umk;   // count unit × per-unit mass
   }
   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;
+    const t = _sumActualRowsKg(b.actualComposition, ingredientsById, formulationsById);
+    if (t != null) return t;
   }
   // Volume-anchored batch (no weighed mass above): mass = measured volume ×
   // measured density (V·ρ — always valid; summing per-ingredient volumes is
@@ -49,25 +90,47 @@ function _batchActualMassKg(b) {
   }
   return null;
 }
-function _batchActualVolume(b) {
+function _batchActualVolume(b, ingredientsById, formulationsById) {
   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);
+  const d = parseFloat(b.measuredDensity), m = _batchActualMassKg(b, ingredientsById, formulationsById);
   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);
+function _actualVolumeInfo(b, ingredientsById, formulationsById) {
+  const av = _batchActualVolume(b, ingredientsById, formulationsById);
   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); }
+  else { const m = _batchActualMassKg(b, ingredientsById, formulationsById); if (m != null && av.liters > 0) out.impliedDensity = +(m / av.liters).toFixed(4); }
   return out;
 }
+// ESTIMATED volume when a batch has no actual: mass (actual, else target) ÷ the
+// formula's declared finished density. Never from an ideal-mix estimate, never
+// an actual. Mirrors the app's _batchEstimatedVolume.
+function _estimatedVolumeInfo(b, f, ingredientsById, formulationsById, batchesById) {
+  if (!f || _batchActualVolume(b, ingredientsById, formulationsById)) return null;
+  const fd = _finishedDensityInfo(f, batchesById);
+  if (!fd) return null;
+  let kg = _batchActualMassKg(b, ingredientsById, formulationsById), basis = 'actual-mass';
+  if (kg == null) { const t = _massToKg(parseFloat(b.targetQuantity), b.unit); if (t != null) { kg = t; basis = 'target-mass'; } }
+  if (kg == null || !(kg > 0)) return null;
+  return { liters: +(kg / fd.value).toFixed(4), unit: 'L', basis, densityUsed: fd.value, densityFromBatch: fd.fromBatch, estimate: true };
+}
+// A VOLUME-target batch's planned mass = target volume × the formula's finished
+// density (what the weigh-out scales by). null density → the app used its
+// ideal-mix estimate; say so rather than reproduce it.
+function _plannedMassInfo(b, f, batchesById) {
+  const L = _volToL(parseFloat(b.targetQuantity), b.unit);
+  if (L == null || !(L > 0)) return null;
+  const fd = _finishedDensityInfo(f, batchesById);
+  if (!fd) return { kg: null, note: 'No finished density declared on the formula — the app scaled this volume target with an ideal-mix estimate from ingredient densities (volumes assumed additive).' };
+  return { kg: +(L * fd.value).toFixed(4), unit: 'kg', densityUsed: fd.value, densitySource: fd.source, densityFromBatch: fd.fromBatch, note: 'Each recipe row weighs out to its wt% of this mass; the balance (q.s.) row is filled to the volume mark, so pure-ingredient volumes do not sum to the target.' };
+}
 
-function _trimBatch(b, formulationsById) {
+function _trimBatch(b, formulationsById, ingredientsById, batchesById) {
   if (!b) return null;
   const f = b.formulationId ? formulationsById.get(b.formulationId) : null;
   return {
@@ -89,11 +152,20 @@ function _trimBatch(b, formulationsById) {
     densityTempC: (b.densityTemp != null && b.densityTemp !== '') ? b.densityTemp : null,
     measuredVolume: b.measuredVolume ?? null,
     measuredVolumeUnit: b.measuredVolumeUnit || '',
-    actualVolume: _actualVolumeInfo(b),
+    actualVolume: _actualVolumeInfo(b, ingredientsById, formulationsById),
+    // No actual volume → an ESTIMATE at the formula's declared finished density
+    // (actual mass, else target mass). `estimate: true`; never an actual.
+    estimatedVolume: _estimatedVolumeInfo(b, f, ingredientsById, formulationsById, batchesById),
     // Actual MASS in kg (the conserved, additive quantity). From actual yield
-    // (mass-unit batch), else summed weighed inputs, else measured volume ×
-    // measured density. null when none is determinable.
-    actualMass: (function () { const m = _batchActualMassKg(b); return (m != null && isFinite(m)) ? { kg: +m.toFixed(4), unit: 'kg' } : null; })(),
+    // (mass-unit batch), else summed as-prepared inputs — each row through its
+    // OWN unit (g directly, mL × that ingredient's density) — else measured
+    // volume × measured density. null when none is determinable.
+    actualMass: (function () { const m = _batchActualMassKg(b, ingredientsById, formulationsById); return (m != null && isFinite(m)) ? { kg: +m.toFixed(4), unit: 'kg' } : null; })(),
+    // Volume-target batches only: the planned mass the weigh-out scaled to.
+    plannedMass: _plannedMassInfo(b, f, batchesById),
+    // The formula's declared finished density (g/mL of the mixed product) that
+    // volume targets and estimates use; null = the app is on its ideal-mix estimate.
+    formulaFinishedDensity: _finishedDensityInfo(f, batchesById),
     preparedDate: b.preparedDate || '',
     preparedBy: b.preparedBy || '',
     // Finished-goods storage location for this batch's produced stock (Production
@@ -167,7 +239,7 @@ const list_batches = {
     return {
       totalMatching: filtered.length,
       returned: Math.min(filtered.length, limit),
-      batches: filtered.slice(0, limit).map(b => _trimBatch(b, indexes.formulationsById)),
+      batches: filtered.slice(0, limit).map(b => _trimBatch(b, indexes.formulationsById, indexes.ingredientsById, indexes.batchesById)),
     };
   },
 };
@@ -202,7 +274,7 @@ const get_batch = {
         })
       : null;
     return {
-      ..._trimBatch(b, indexes.formulationsById),
+      ..._trimBatch(b, indexes.formulationsById, indexes.ingredientsById, indexes.batchesById),
       notes: b.notes || '',
       equipmentUsed: b.equipmentUsed || '',
       // Multi-select equipment: full list [{name, equipmentId}]; falls back to