formlab-mcp 0.6.18 → 0.6.20

package/README.md

@@ -33,11 +33,11 @@ Ask Claude (or another MCP client) things like:
 | `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 / 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` |
+| `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**, **approved sources** (the suppliers / manufacturers qualified to supply this material — ASL/AML), and **inventory lots** (balances + expiry + the source each was received from). 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, **unit cost**, **status** — `active` / `hold` / `quarantine` / `rejected`; held lots are blocked from consumption, with a `holdReason` — and the **approved source** it was received from: `source.supplier` + `source.manufacturer`, where recalls hinge on the manufacturer). Filters: `ingredient_id`, `expiring_within_days`, `status` (e.g. `hold` to find lots held for a recall) |
 | `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 |
+| `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) |
 | `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.18",
+  "version": "0.6.20",
   "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.18",
+  "version": "0.6.20",
   "websiteUrl": "https://formvix.com/mcp",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.6.18",
+      "version": "0.6.20",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tools/ingredients.js

@@ -74,9 +74,27 @@ function _trimIngredient(i) {
     ...(i.surfactantDetails ? { surfactantDetails: i.surfactantDetails } : {}),
     ...(i.pigmentDetails    ? { pigmentDetails:    i.pigmentDetails }    : {}),
     ...(i.fragranceDetails  ? { fragranceDetails:  i.fragranceDetails }  : {}),
+    // Approved sources (ASL/AML): the suppliers/manufacturers qualified to supply
+    // this material. A received lot names one via lot.sourceId. Manufacturer is
+    // the recall/equivalence-relevant party; supplier is who you buy from.
+    ...(Array.isArray(i.sources) && i.sources.length ? { sources: i.sources.map(s => ({
+      id: s.id, supplier: s.supplier || '', manufacturer: s.manufacturer || '',
+      partNo: s.partNo || '', grade: s.grade || '', status: s.status || 'qualified',
+      primary: !!s.primary,
+    })) } : {}),
   };
 }
 
+// Resolve the approved source a lot was received from (lot.sourceId → the
+// ingredient's ing.sources[]). Null when the lot predates sources or is unlinked.
+function _lotSourceInfo(l) {
+  if (!l || !l.sourceId) return null;
+  const ing = (db.ingredients || []).find(i => i && i.id === l.ingredientId);
+  const s = (ing && Array.isArray(ing.sources)) ? ing.sources.find(x => x.id === l.sourceId) : null;
+  if (!s) return null;
+  return { sourceId: s.id, supplier: s.supplier || '', manufacturer: s.manufacturer || '', status: s.status || 'qualified' };
+}
+
 const list_ingredients = {
   definition: {
     name: 'list_ingredients',
@@ -130,7 +148,7 @@ const list_ingredients = {
 const get_ingredient = {
   definition: {
     name: 'get_ingredient',
-    description: 'Get full details for a single ingredient: cost ($/kg), GHS safety (pictograms / H- / P-codes / signal word), per-jurisdiction regulatory status, inventory lots (balances + expiry), recent stock movements, and the formulations using it. Accepts internal id or UID (e.g. ING-001).',
+    description: 'Get full details for a single ingredient: cost ($/kg), GHS safety (pictograms / H- / P-codes / signal word), per-jurisdiction regulatory status, approved sources (the suppliers/manufacturers qualified to supply this material — ASL/AML), inventory lots (balances + expiry + the source each was received from), recent stock movements, and the formulations using it. Accepts internal id or UID (e.g. ING-001).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -176,6 +194,7 @@ const get_ingredient = {
         qtyRemaining: l.qtyRemaining, qtyReceived: l.qtyReceived, unit: l.unit || '',
         receivedDate: l.receivedDate || null, expiryDate: l.expiryDate || null,
         supplier: l.supplier || '', status: l.status || 'active',
+        sourceId: l.sourceId || null, source: _lotSourceInfo(l),
       }));
     return {
       ..._trimIngredient(ing),
@@ -295,13 +314,13 @@ const find_by_smarts = {
 const list_lots = {
   definition: {
     name: 'list_lots',
-    description: 'List inventory lots (received batches of an ingredient, each with its own remaining balance, supplier, and expiry). Optionally filter by ingredient, expiring-within-days, or status. For one ingredient\'s full lots + traceability, use get_ingredient.',
+    description: 'List inventory lots (received batches of an ingredient, each with its own remaining balance, supplier, expiry, and unit cost). Each lot also carries the approved source it was received from (source.supplier + source.manufacturer; recalls hinge on the manufacturer), or null for lots predating sources. Optionally filter by ingredient, expiring-within-days, or status. A lot\'s status can be "active", "hold" (a manual QC / recall hold — see holdReason), "quarantine", or "rejected"; the last three are blocked from auto-consumption. For one ingredient\'s full lots + traceability, use get_ingredient.',
     inputSchema: {
       type: 'object',
       properties: {
         ingredient_id: { type: 'string', description: 'Only lots for this ingredient (internal id or UID, e.g. ING-001).' },
         expiring_within_days: { type: 'number', description: 'Only lots whose expiryDate is within this many days from now (negative days = already expired are always included).' },
-        status: { type: 'string', description: 'Filter by lot status (e.g. "active").' },
+        status: { type: 'string', description: 'Filter by lot status: "active", "hold", "quarantine", or "rejected". Held/quarantined/rejected lots are blocked from auto-consumption (use "hold" to find lots put on hold for a QC / recall).' },
         limit: { type: 'number', description: 'Max rows (default 200, max 1000).' },
       },
     },
@@ -332,6 +351,15 @@ const list_lots = {
       qtyRemaining: l.qtyRemaining, qtyReceived: l.qtyReceived, unit: l.unit || '',
       receivedDate: l.receivedDate || null, expiryDate: l.expiryDate || null,
       supplier: l.supplier || '', status: l.status || 'active',
+      // Approved source this lot was received from (supplier + manufacturer);
+      // null for lots received before sources existed. Recalls hinge on the
+      // manufacturer, so it is surfaced explicitly here.
+      sourceId: l.sourceId || null, source: _lotSourceInfo(l),
+      // 'hold' / 'quarantine' / 'rejected' lots are blocked from auto-consumption;
+      // holdReason explains a manual hold (QC / recall).
+      holdReason: l.holdReason || '',
+      unitCost: (l.unitCost != null && l.unitCost !== '') ? l.unitCost : null,
+      unitCostCcy: l.unitCostCcy || null,
     }));
     return { totalMatching: rows.length, returned: Math.min(rows.length, limit), lots: rows.slice(0, limit) };
   },

package/tools/lab.js

@@ -96,6 +96,9 @@ function _trimBatch(b, formulationsById) {
     actualMass: (function () { const m = _batchActualMassKg(b); return (m != null && isFinite(m)) ? { kg: +m.toFixed(4), unit: 'kg' } : null; })(),
     preparedDate: b.preparedDate || '',
     preparedBy: b.preparedBy || '',
+    // Finished-goods storage location for this batch's produced stock (Production
+    // Inventory: a batch is a finished-goods lot).
+    location: b.location || '',
     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.
@@ -172,7 +175,7 @@ const list_batches = {
 const get_batch = {
   definition: {
     name: 'get_batch',
-    description: 'Get full details for a single batch including its actual composition (as-prepared, when logged), child samples, lineage (parent / sub-blend parents), inventory consumption note, and finished-product density + actual volume (measured directly or derived as actual mass ÷ measured density — never summed from per-ingredient volumes). Accepts internal id or UID.',
+    description: 'Get full details for a single batch including its actual composition (as-prepared, when logged), child samples, lineage (parent / sub-blend parents), and — treating the batch as a finished-goods lot — its storage `location` and finished-goods `stockLedger` (shipments out + adjustments; on-hand = produced − sample pulls − sub-batch draws + Σ ledger). Plus finished-product density + actual volume (measured directly or derived as actual mass ÷ measured density — never summed from per-ingredient volumes). Accepts internal id or UID.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -212,6 +215,14 @@ const get_batch = {
       sourceBlendParents: parents,
       samples: samples.map(s => ({ id: s.id, uid: s.uid, name: s.name || '', status: s.status })),
       sampleCount: samples.length,
+      // Finished-goods drawdown ledger (a batch is a finished-goods lot): shipments
+      // out + manual adjustments, in the batch unit. On-hand = produced − sample
+      // pulls − sub-batch draws + Σ(ledger deltas). Sub-batches are batches whose
+      // parentBatchId === this id (see list_batches).
+      stockLedger: (Array.isArray(b.stockLedger) ? b.stockLedger : []).map(e => ({
+        date: e.ts || null, delta: e.delta ?? null, unit: e.unit || b.unit || '', kind: e.kind || '', note: e.note || '',
+      })),
+      shippedQty: (Array.isArray(b.stockLedger) ? b.stockLedger : []).reduce((s, e) => e.kind === 'shipment' ? s + Math.abs(parseFloat(e.delta) || 0) : s, 0),
     };
   },
 };