formlab-mcp 0.6.13 → 0.6.15

package/README.md

@@ -45,6 +45,8 @@ Ask Claude (or another MCP client) things like:
 | `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) |
+| `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` |
+| `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 |
 | `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` |
@@ -146,7 +148,7 @@ Or for local-dev (from the repo):
 }
 ```
 
-Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 34 tools become callable in any conversation.
+Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 36 tools become callable in any conversation.
 
 ## Wire it up to Claude Code
 

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.
 
-**34 read-only tools** covering formulations, ingredients, batches, samples,
+**36 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.

package/index.js

@@ -7,7 +7,7 @@
 //   FORMLAB_EXPORT=/path/to/export.json node index.js
 //   formlab-mcp /path/to/export.json   (when installed via npm)
 //
-// Exposes 33 tools (see ./tools/) over stdio. The MCP host (Claude
+// Exposes 36 tools (see ./tools/) over stdio. The MCP host (Claude
 // Desktop, Claude Code, etc.) handles tool discovery, invocation
 // and response formatting. We just register handlers and stay out
 // of the way.
@@ -37,6 +37,7 @@ import * as designspace  from './tools/designspace.js';
 import * as library      from './tools/library.js';
 import * as projects     from './tools/projects.js';
 import * as notebook     from './tools/notebook.js';
+import * as batchAnalyze from './tools/batch-analyze.js';
 
 // ----- Data source: LIVE cloud workspace OR a static export file -----
 // Cloud mode kicks in when a dedicated read-only MCP token is present (mint it
@@ -116,6 +117,7 @@ const TOOLS = [
   ...Object.values(library.tools),
   ...Object.values(projects.tools),
   ...Object.values(notebook.tools),
+  ...Object.values(batchAnalyze.tools),
 ];
 
 // Version reported in the MCP handshake. Read from package.json rather than

package/package.json

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

package/tools/batch-analyze.js

@@ -0,0 +1,234 @@
+// ============================================================
+// Batch analysis tools (read-only) — parity with the in-app Batch Analyze panel
+// (js/views/batches-compare.js). Spec: docs/MCP_BATCH_ANALYZE_SPEC.md.
+//   - compare_batches: reproducibility of N runs (yield / produced / cost,
+//     per-ingredient drift vs the proposal, outlier run).
+//   - get_batch_pivot: production analytics (group_by × metric).
+// Computes from the SAME primitives as the app so numbers match: flattened
+// wt-% (data.js flattenComposition), _batchActualMassKg (tools/lab.js),
+// _costPerKg (tools/ingredients.js).
+// ============================================================
+
+import { getStore, resolveById, flattenComposition } from '../data.js';
+import { _batchActualMassKg, _massToKg } from './lab.js';
+import { _costPerKg } from './ingredients.js';
+
+// ---- shared compute (mirrors _bcActualPctMap / _bcProposedPctMap / _bcSpreadLevel) ----
+function _pctMap(compositionHost) {
+  const out = new Map();
+  if (!compositionHost) return out;
+  const flat = flattenComposition(compositionHost);
+  for (const r of (flat.rows || [])) {
+    if (!r.ingredientId) continue;
+    out.set(r.ingredientId, (out.get(r.ingredientId) || 0) + r.weightFraction * 100);
+  }
+  for (const [k, v] of out) out.set(k, +v.toFixed(4));
+  return out;
+}
+const _actualPctMap = b => (Array.isArray(b.actualComposition) && b.actualComposition.length)
+  ? _pctMap({ composition: b.actualComposition }) : new Map();
+const _proposedPctMap = f => f ? _pctMap(f) : new Map();
+
+// Actual amount (as entered) per ingredient — top-level rows only, {amount, unit}.
+function _amountMap(b) {
+  const out = new Map();
+  for (const c of (b.actualComposition || [])) {
+    if (!c || !c.ingredientId) continue;
+    const amt = parseFloat(c.amount);
+    if (!isFinite(amt)) continue;
+    const prev = out.get(c.ingredientId);
+    if (!prev) out.set(c.ingredientId, { amount: amt, unit: c.unit || '' });
+    else out.set(c.ingredientId, { amount: prev.amount + amt, unit: prev.unit });
+  }
+  return out;
+}
+
+function _targetKg(b) { const q = parseFloat(b.targetQuantity); return isFinite(q) ? _massToKg(q, b.unit) : null; }
+function _yieldPct(b) { const tk = _targetKg(b), mk = _batchActualMassKg(b); return (tk && tk > 0 && mk != null) ? +(mk / tk * 100).toFixed(1) : null; }
+
+// Blend cost per kg = Σ ingredient costPerKg × weightFraction over the flattened
+// composition (actual if logged, else the linked formula). Purity gross-up and
+// currency conversion the app applies are NOT modeled here — this is a
+// currency-per-kg estimate in each ingredient's own cost currency.
+function _batchCostPerKg(b, formula) {
+  const db = getStore().db;
+  const host = (Array.isArray(b.actualComposition) && b.actualComposition.length) ? { composition: b.actualComposition } : formula;
+  if (!host) return null;
+  const flat = flattenComposition(host);
+  let sum = 0, any = false;
+  for (const r of (flat.rows || [])) {
+    const ing = (db.ingredients || []).find(i => i.id === r.ingredientId);
+    const cpk = ing ? _costPerKg(ing) : null;
+    if (cpk != null) { sum += cpk * r.weightFraction; any = true; }
+  }
+  return any ? +sum.toFixed(4) : null;
+}
+
+// Drift severity across a run of values. wt%: absolute + relative thresholds;
+// amount: relative-only (units differ). 0 consistent, 1 minor, 2 large.
+function _spreadLevel(vals, relOnly) {
+  if (!vals || vals.length < 2) return { level: 0, spread: 0 };
+  const max = Math.max(...vals), min = Math.min(...vals), spread = max - min;
+  const mean = vals.reduce((a, b) => a + b, 0) / vals.length;
+  const rel = mean > 0 ? spread / mean : (spread > 0 ? 1 : 0);
+  let level = 0;
+  if (relOnly) { if (rel >= 0.15) level = 2; else if (rel >= 0.05) level = 1; }
+  else { if (spread >= 1 || rel >= 0.15) level = 2; else if (spread >= 0.25 || rel >= 0.05) level = 1; }
+  return { level, spread: +spread.toFixed(4) };
+}
+
+function _batchTestCount(b, db) {
+  const sIds = new Set((db.samples || []).filter(s => s.batchId === b.id).map(s => s.id));
+  return (db.testResults || []).filter(t => sIds.has(t.sampleId)).length;
+}
+
+// ============================================================
+// compare_batches
+// ============================================================
+const compare_batches = {
+  definition: {
+    name: 'compare_batches',
+    description: 'Compare 2+ batches (ideally runs of ONE formula) for reproducibility: each run\'s yield %, actual produced mass, and cost/kg; per-ingredient drift across the runs vs the formula\'s proposed wt-%; and the biggest outlier run. Best for "are these runs consistent / which drifted / which is the outlier". basis="wt_percent" (default, size-normalized) or "amount" (as-entered).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        batch_uids: { type: 'array', items: { type: 'string' }, description: 'Batch ids or UIDs (e.g. ["BATCH-0017","BATCH-0019"]). 2 or more.' },
+        basis: { type: 'string', enum: ['wt_percent', 'amount'], description: 'wt_percent (default) or amount (as entered, top-level rows).' },
+      },
+      required: ['batch_uids'],
+    },
+  },
+  handler: async (args) => {
+    if (!Array.isArray(args.batch_uids) || args.batch_uids.length < 2) return { error: 'Pass at least 2 batch ids/uids.' };
+    const db = getStore().db;
+    const batches = args.batch_uids.map(id => resolveById('batches', id)).filter(Boolean);
+    if (batches.length < 2) return { error: 'Fewer than 2 of the supplied ids resolved to existing batches.' };
+    const basis = args.basis === 'amount' ? 'amount' : 'wt_percent';
+
+    const cols = batches.map(b => {
+      const f = (db.formulations || []).find(x => x.id === b.formulationId) || null;
+      const hasActual = Array.isArray(b.actualComposition) && b.actualComposition.length > 0;
+      const mk = _batchActualMassKg(b);
+      return { b, f, hasActual, actMap: _actualPctMap(b), amtMap: _amountMap(b),
+        yield_pct: _yieldPct(b), produced_kg: mk != null ? +mk.toFixed(4) : null, cost_per_kg: _batchCostPerKg(b, f) };
+    });
+    const fIds = new Set(batches.map(b => b.formulationId));
+    const shared = fIds.size === 1 ? cols[0].f : null;
+    const proposed = (basis === 'wt_percent' && shared) ? _proposedPctMap(shared) : new Map();
+    const colsAct = cols.filter(c => c.hasActual);
+
+    // ingredient universe
+    const ingIds = new Set();
+    proposed.forEach((_v, k) => ingIds.add(k));
+    cols.forEach(c => (basis === 'amount' ? c.amtMap : c.actMap).forEach((_v, k) => ingIds.add(k)));
+
+    const composition = [...ingIds].map(ingId => {
+      const ing = (db.ingredients || []).find(i => i.id === ingId);
+      const runs = {};
+      const present = [];
+      let unit = null, sameUnit = true;
+      colsAct.forEach(c => {
+        const uid = c.b.uid || c.b.id;
+        if (basis === 'amount') {
+          const e = c.amtMap.get(ingId);
+          if (e) { runs[uid] = +(+e.amount).toFixed(4); present.push(e.amount); if (unit == null) unit = e.unit; else if (unit !== e.unit) sameUnit = false; }
+        } else {
+          if (c.actMap.has(ingId)) { runs[uid] = c.actMap.get(ingId); present.push(c.actMap.get(ingId)); }
+        }
+      });
+      const sev = (present.length >= 2 && (basis === 'wt_percent' || sameUnit)) ? _spreadLevel(present, basis === 'amount') : { level: 0, spread: 0 };
+      const row = { ingredient: ing?.name || ingId, cas: ing?.cas || ing?.casNumber || '', runs, spread: sev.spread, drift_level: sev.level };
+      if (basis === 'wt_percent') row.proposed_wt_pct = proposed.has(ingId) ? proposed.get(ingId) : null;
+      if (basis === 'amount' && unit) row.unit = unit;
+      return row;
+    }).sort((a, b) => b.drift_level - a.drift_level || b.spread - a.spread || String(a.ingredient).localeCompare(b.ingredient));
+
+    // outlier: max summed |Δ from cross-run mean| leading the runner-up by >15% (wt% basis, 3+ runs)
+    let outlier_uid = null;
+    if (basis === 'wt_percent' && colsAct.length >= 3) {
+      const union = new Set(); colsAct.forEach(c => c.actMap.forEach((_v, k) => union.add(k)));
+      const mean = new Map();
+      union.forEach(id => { const p = colsAct.filter(c => c.actMap.has(id)); if (p.length >= 2) mean.set(id, p.reduce((s, c) => s + c.actMap.get(id), 0) / p.length); });
+      const scores = colsAct.map(c => { let s = 0; mean.forEach((mv, id) => { if (c.actMap.has(id)) s += Math.abs(c.actMap.get(id) - mv); }); return { uid: c.b.uid || c.b.id, s }; }).sort((a, b) => b.s - a.s);
+      if (scores.length >= 2 && scores[0].s > 0 && scores[0].s > scores[1].s * 1.15) outlier_uid = scores[0].uid;
+    }
+    const drifting = composition.filter(r => r.drift_level >= 1).length;
+
+    return {
+      runs: cols.map(c => ({
+        uid: c.b.uid || c.b.id, formula: (c.f && c.f.name) || c.b.formulationName || null,
+        status: c.b.status || null, prepared_date: c.b.preparedDate || null, prepared_by: c.b.preparedBy || null,
+        target: c.b.targetQuantity != null ? { qty: c.b.targetQuantity, unit: c.b.unit || null } : null,
+        actual_produced_kg: c.produced_kg, yield_pct: c.yield_pct, cost_per_kg: c.cost_per_kg,
+        has_actual_composition: c.hasActual, is_outlier: (c.b.uid || c.b.id) === outlier_uid,
+      })),
+      basis, shared_formula: shared ? shared.name : null,
+      composition,
+      summary: { runs_with_actuals: colsAct.length, drifting_ingredients: drifting, outlier_uid, consistent: colsAct.length >= 2 && drifting === 0 },
+    };
+  },
+};
+
+// ============================================================
+// get_batch_pivot
+// ============================================================
+const _GROUP_LABEL = { formula: 'Formula', status: 'Status', month: 'Month', prepared_by: 'Prepared by', project: 'Project' };
+const _METRIC_LABEL = { count: 'Batch count', avg_yield_pct: 'Avg yield %', total_produced_kg: 'Total produced (kg)', avg_cost_per_batch: 'Avg cost / batch', total_samples: 'Total samples', total_tests: 'Total tests' };
+
+function _groupKey(b, groupBy, db) {
+  if (groupBy === 'status') return b.status || '(no status)';
+  if (groupBy === 'month') return (b.preparedDate || '').slice(0, 7) || '(no date)';
+  if (groupBy === 'prepared_by') return b.preparedBy || '(unknown)';
+  if (groupBy === 'project') { const f = (db.formulations || []).find(x => x.id === b.formulationId); const p = f && (db.projects || []).find(pp => pp.id === f.projectId); return p ? (p.name || '(project)') : '(no project)'; }
+  return b.formulationName || ((db.formulations || []).find(f => f.id === b.formulationId) || {}).name || '(no formula)';
+}
+function _metricVal(bs, metric, db) {
+  if (metric === 'count') return bs.length;
+  if (metric === 'avg_yield_pct') { const ys = bs.map(_yieldPct).filter(v => v != null); return ys.length ? +(ys.reduce((a, b) => a + b, 0) / ys.length).toFixed(1) : null; }
+  if (metric === 'total_produced_kg') { let kg = 0, any = false; bs.forEach(b => { const m = _batchActualMassKg(b); if (m != null && isFinite(m)) { kg += m; any = true; } }); return any ? +kg.toFixed(3) : null; }
+  if (metric === 'avg_cost_per_batch') { const cs = bs.map(b => { const f = (db.formulations || []).find(x => x.id === b.formulationId) || null; const perKg = _batchCostPerKg(b, f); const mk = _batchActualMassKg(b) || _targetKg(b); return (perKg != null && mk != null) ? perKg * mk : null; }).filter(v => v != null); return cs.length ? +(cs.reduce((a, b) => a + b, 0) / cs.length).toFixed(2) : null; }
+  if (metric === 'total_samples') return bs.reduce((s, b) => s + (db.samples || []).filter(sm => sm.batchId === b.id).length, 0);
+  if (metric === 'total_tests') return bs.reduce((s, b) => s + _batchTestCount(b, db), 0);
+  return 0;
+}
+
+const get_batch_pivot = {
+  definition: {
+    name: 'get_batch_pivot',
+    description: 'Aggregate batches by a dimension (formula / status / month / prepared_by / project) and a batch-native metric (count, avg_yield_pct, total_produced_kg, avg_cost_per_batch, total_samples, total_tests). The "lab-manager" production view. Optionally scope to specific batch_uids and/or a status filter.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        group_by: { type: 'string', enum: ['formula', 'status', 'month', 'prepared_by', 'project'], description: 'Grouping dimension (default formula).' },
+        metric: { type: 'string', enum: ['count', 'avg_yield_pct', 'total_produced_kg', 'avg_cost_per_batch', 'total_samples', 'total_tests'], description: 'Metric per group (default count).' },
+        batch_uids: { type: 'array', items: { type: 'string' }, description: 'Optional — scope to these batches; omit for all.' },
+        status: { type: 'string', description: 'Optional status filter (e.g. "Completed").' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const db = getStore().db;
+    const groupBy = _GROUP_LABEL[args.group_by] ? args.group_by : 'formula';
+    const metric = _METRIC_LABEL[args.metric] ? args.metric : 'count';
+    let batches = db.batches || [];
+    let scope = 'all';
+    if (Array.isArray(args.batch_uids) && args.batch_uids.length) {
+      const ids = new Set(args.batch_uids.map(u => { const b = resolveById('batches', u); return b ? b.id : null; }).filter(Boolean));
+      batches = batches.filter(b => ids.has(b.id));
+      scope = 'selected';
+    }
+    if (args.status) batches = batches.filter(b => String(b.status || '').toLowerCase() === String(args.status).toLowerCase());
+
+    const groups = {};
+    batches.forEach(b => { const k = _groupKey(b, groupBy, db); (groups[k] = groups[k] || []).push(b); });
+    const additive = ['count', 'total_produced_kg', 'total_samples', 'total_tests'].includes(metric);
+    const rows = Object.entries(groups).map(([key, bs]) => ({ key, batches: bs.length, value: _metricVal(bs, metric, db) }))
+      .sort((a, b) => (b.value == null ? -Infinity : b.value) - (a.value == null ? -Infinity : a.value) || a.key.localeCompare(b.key));
+    const total = additive ? +rows.reduce((s, r) => s + (r.value || 0), 0).toFixed(3) : null;
+    if (additive && total) rows.forEach(r => { r.share_pct = +((r.value || 0) / total * 100).toFixed(1); });
+
+    return { group_by: groupBy, group_by_label: _GROUP_LABEL[groupBy], metric, metric_label: _METRIC_LABEL[metric], scope, batch_count: batches.length, additive, total, rows };
+  },
+};
+
+export const tools = { compare_batches, get_batch_pivot };

package/tools/ingredients.js

@@ -415,3 +415,6 @@ const list_inventory = {
 };
 
 export const tools = { list_ingredients, get_ingredient, find_by_smarts, list_lots, list_inventory };
+
+// Exported for the batch-analyze tools (avg cost metric) to reuse the same cost normalization.
+export { _costPerKg, _densityKgPerL };

package/tools/lab.js

@@ -189,6 +189,11 @@ const get_batch = {
       ..._trimBatch(b, indexes.formulationsById),
       notes: b.notes || '',
       equipmentUsed: b.equipmentUsed || '',
+      // Multi-select equipment: full list [{name, equipmentId}]; falls back to
+      // the legacy single equipmentUsed so older batches still report one item.
+      equipmentUsedList: (Array.isArray(b.equipmentUsedList) && b.equipmentUsedList.length)
+        ? b.equipmentUsedList.filter(e => e && e.name).map(e => ({ name: e.name, equipmentId: e.equipmentId || null }))
+        : (b.equipmentUsed ? [{ name: b.equipmentUsed, equipmentId: b.equipmentUsedId || null }] : []),
       actualCompositionRowCount: Array.isArray(b.actualComposition) ? b.actualComposition.length : 0,
       hasActualComposition: Array.isArray(b.actualComposition) && b.actualComposition.length > 0,
       sourceBlendParents: parents,
@@ -296,3 +301,6 @@ const get_sample = {
 };
 
 export const tools = { list_batches, get_batch, list_samples, get_sample };
+
+// Exported for the batch-analyze tools so they reuse the SAME mass logic.
+export { _batchActualMassKg, _massToKg };