formlab-mcp 0.6.20 → 0.6.22

package/README.md

@@ -35,6 +35,8 @@ Ask Claude (or another MCP client) things like:
 | `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**, **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_suppliers` | Supplier / manufacturer records with roll-ups — ingredients approved, lots received / on hand (+ value at paid cost), qualified / trial / disqualified source counts, last receipt; lots count by supplier **and** by manufacturer |
+| `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) |
@@ -149,7 +151,7 @@ Or for local-dev (from the repo):
 }
 ```
 
-Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 37 tools become callable in any conversation.
+Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 39 tools become callable in any conversation.
 
 ## Wire it up to Claude Code
 

package/index.js

@@ -38,6 +38,7 @@ 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';
+import * as suppliers    from './tools/suppliers.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
@@ -117,6 +118,7 @@ const TOOLS = [
   ...Object.values(library.tools),
   ...Object.values(projects.tools),
   ...Object.values(notebook.tools),
+  ...Object.values(suppliers.tools),
   ...Object.values(batchAnalyze.tools),
 ];
 

package/package.json

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

package/supabase/.temp/linked-project.json

@@ -0,0 +1 @@
+{"ref":"ufizhypibwqqpavhxdwt","name":"FormLab","organization_id":"pbplgvokbayhflgrvygl","organization_slug":"pbplgvokbayhflgrvygl"}

package/tools/ingredients.js

@@ -79,6 +79,7 @@ function _trimIngredient(i) {
     // 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 || '',
+      supplierId: s.supplierId || null, manufacturerId: s.manufacturerId || null,   // db.suppliers ids (get_supplier)
       partNo: s.partNo || '', grade: s.grade || '', status: s.status || 'qualified',
       primary: !!s.primary,
     })) } : {}),
@@ -89,10 +90,14 @@ function _trimIngredient(i) {
 // ingredient's ing.sources[]). Null when the lot predates sources or is unlinked.
 function _lotSourceInfo(l) {
   if (!l || !l.sourceId) return null;
+  // `db` is NOT module-scoped here — handlers pull it from getStore() — so do the
+  // same. (0.6.20 shipped a bare `db` reference; it was masked by the guard above
+  // until the first lot with a sourceId existed, then threw "db is not defined".)
+  const { db } = getStore();
   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' };
+  return { sourceId: s.id, supplier: s.supplier || '', manufacturer: s.manufacturer || '', supplierId: s.supplierId || null, manufacturerId: s.manufacturerId || null, status: s.status || 'qualified' };
 }
 
 const list_ingredients = {
@@ -193,7 +198,7 @@ const get_ingredient = {
         id: l.id, uid: l.uid, lotNumber: l.lotNumber || '',
         qtyRemaining: l.qtyRemaining, qtyReceived: l.qtyReceived, unit: l.unit || '',
         receivedDate: l.receivedDate || null, expiryDate: l.expiryDate || null,
-        supplier: l.supplier || '', status: l.status || 'active',
+        supplier: l.supplier || '', supplierId: l.supplierId || null, status: l.status || 'active',
         sourceId: l.sourceId || null, source: _lotSourceInfo(l),
       }));
     return {
@@ -350,7 +355,7 @@ const list_lots = {
       ingredientId: l.ingredientId, ingredientName: nameById.get(l.ingredientId) || '',
       qtyRemaining: l.qtyRemaining, qtyReceived: l.qtyReceived, unit: l.unit || '',
       receivedDate: l.receivedDate || null, expiryDate: l.expiryDate || null,
-      supplier: l.supplier || '', status: l.status || 'active',
+      supplier: l.supplier || '', supplierId: l.supplierId || null, 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.

package/tools/suppliers.js

@@ -0,0 +1,187 @@
+// =====================================================================
+// SUPPLIERS — list_suppliers / get_supplier (traceability Phase 2d).
+// Mirrors js/views/suppliers.js: one record per supplier / manufacturer;
+// references are matched by supplierId / manufacturerId, falling back to a
+// normalised name match for records stamped before entities existed. Lots
+// count for a supplier both when bought from it AND when the approved source
+// names it as the manufacturer — a maker's recall must reach lots bought
+// through a distributor. Read-only, like every tool here.
+// =====================================================================
+import { getStore, resolveById } from '../data.js';
+
+const SUFFIX_RE = /\b(inc|incorporated|ltd|limited|llc|gmbh|co|corp|corporation|company|ag|sa|plc|bv|nv|srl|s\.?a\.?|pty)\b\.?$/i;
+function norm(name) {
+  let s = String(name == null ? '' : name).toLowerCase().replace(/\s+/g, ' ').trim().replace(/[\s,.\-]+$/g, '');
+  const stripped = s.replace(SUFFIX_RE, '').replace(/[\s,.\-]+$/g, '').trim();
+  return stripped || s;
+}
+function live(x) { return x && !x._trashed && !x.deletedAt; }
+function resolveLotSource(lot, ing) {
+  if (!lot || !ing) return null;
+  const list = Array.isArray(ing.sources) ? ing.sources : [];
+  if (lot.sourceId) { const s = list.find(x => x && x.id === lot.sourceId); if (s) return s; }
+  const k = norm(lot.supplier); if (!k) return null;
+  return list.find(s => s && (norm(s.supplier) === k || norm(s.manufacturer) === k)) || null;
+}
+// Everything that points at a supplier record.
+function refsOf(db, sup) {
+  const id = sup.id, key = norm(sup.name);
+  const hits = (sid, name) => (sid && sid === id) || (!sid && key && norm(name) === key);
+  const ingredients = [], sources = [], lots = [];
+  (db.ingredients || []).forEach(ing => {
+    if (!live(ing)) return;
+    let hit = hits(ing.supplierId, ing.supplier);
+    (ing.sources || []).forEach(s => {
+      if (!s) return;
+      const asSup = hits(s.supplierId, s.supplier), asMan = hits(s.manufacturerId, s.manufacturer);
+      if (asSup || asMan) { sources.push({ ing, src: s, role: asSup && asMan ? 'both' : (asSup ? 'supplier' : 'manufacturer') }); hit = true; }
+    });
+    if (hit) ingredients.push(ing);
+  });
+  (db.lots || []).forEach(lot => {
+    if (!live(lot)) return;
+    const ing = (db.ingredients || []).find(i => i.id === lot.ingredientId);
+    let hit = hits(lot.supplierId, lot.supplier);
+    if (!hit && lot.sourceId && ing) { const s = resolveLotSource(lot, ing); if (s && (hits(s.supplierId, s.supplier) || hits(s.manufacturerId, s.manufacturer))) hit = true; }
+    if (hit) lots.push({ lot, ing });
+  });
+  return { ingredients, sources, lots };
+}
+function consumersOfLot(moves, lotId) {
+  const map = Object.create(null);
+  for (const m of (moves || [])) {
+    if (!m || m.lotId !== lotId) continue;
+    const d = parseFloat(m.delta); if (!isFinite(d) || d >= 0) continue;
+    const key = m.batchId ? ('batch ' + m.batchId) : m.sampleId ? ('sample ' + m.sampleId) : 'other ';
+    map[key] = +((map[key] || 0) + (-d)).toFixed(6);
+  }
+  return Object.keys(map).map(k => { const i = k.indexOf(' '); return { kind: k.slice(0, i), id: k.slice(i + 1) || null, qty: map[k] }; });
+}
+function rowOf(db, sup) {
+  const refs = refsOf(db, sup);
+  const qs = { qualified: 0, trial: 0, disqualified: 0 };
+  refs.sources.forEach(x => { const st = x.src.status || 'qualified'; if (qs[st] != null) qs[st]++; });
+  let onHandLots = 0, onHandValue = null, valueCcy = null, lastReceived = '';
+  refs.lots.forEach(({ lot }) => {
+    const rem = parseFloat(lot.qtyRemaining), cost = parseFloat(lot.unitCost);
+    if (rem > 0) onHandLots++;
+    if (rem > 0 && isFinite(cost)) { const ccy = lot.unitCostCcy || 'USD'; if (!valueCcy || valueCcy === ccy) { valueCcy = ccy; onHandValue = (onHandValue || 0) + rem * cost; } }
+    if (lot.receivedDate && lot.receivedDate > lastReceived) lastReceived = lot.receivedDate;
+  });
+  return {
+    id: sup.id, uid: sup.uid || '', name: sup.name || '', kind: sup.kind || 'supplier',
+    country: sup.country || '', contact: sup.contact || '', email: sup.email || '', phone: sup.phone || '', website: sup.website || '',
+    ingredientCount: refs.ingredients.length, lotCount: refs.lots.length, lotsOnHand: onHandLots,
+    onHandValue: onHandValue == null ? null : +onHandValue.toFixed(2), onHandValueCcy: onHandValue == null ? null : valueCcy,
+    qualifiedSources: qs.qualified, trialSources: qs.trial, disqualifiedSources: qs.disqualified,
+    lastReceived: lastReceived ? lastReceived.slice(0, 10) : null,
+    _refs: refs,
+  };
+}
+
+const list_suppliers = {
+  definition: {
+    name: 'list_suppliers',
+    description: 'List supplier / manufacturer records with roll-ups: how many ingredients name each one as an approved source, lots received (and still on hand, with on-hand value at paid cost), qualified / trial / disqualified source counts, and last receipt date. Lots count for a supplier both when bought from it and when it is the MANUFACTURER behind a distributor. Filter by kind, country, stock on hand, open trials, or a name/ingredient search.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', description: '"supplier", "manufacturer" or "both".' },
+        country: { type: 'string', description: 'Case-insensitive country match.' },
+        with_stock: { type: 'boolean', description: 'Only suppliers with at least one lot still on hand.' },
+        has_trial: { type: 'boolean', description: 'Only suppliers with a source still on trial (qualification pending).' },
+        has_disqualified: { type: 'boolean', description: 'Only suppliers with a disqualified source.' },
+        search: { type: 'string', description: 'Substring match on supplier name, country, contact — or the name of an ingredient it supplies.' },
+        limit: { type: 'number', description: 'Max rows (default 200, max 1000).' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const limit = Math.min(1000, Math.max(1, args.limit || 200));
+    const q = (args.search || '').trim().toLowerCase();
+    const rows = (db.suppliers || []).filter(live).map(s => rowOf(db, s)).filter(r => {
+      if (args.kind && String(r.kind).toLowerCase() !== String(args.kind).toLowerCase()) return false;
+      if (args.country && String(r.country).toLowerCase() !== String(args.country).toLowerCase()) return false;
+      if (args.with_stock && !(r.lotsOnHand > 0)) return false;
+      if (args.has_trial && !(r.trialSources > 0)) return false;
+      if (args.has_disqualified && !(r.disqualifiedSources > 0)) return false;
+      if (q) {
+        const hay = [r.name, r.uid, r.country, r.contact, r.email, ...r._refs.ingredients.map(i => i.name || '')].join(' ').toLowerCase();
+        if (!hay.includes(q)) return false;
+      }
+      return true;
+    }).sort((a, b) => a.name.localeCompare(b.name));
+    return { totalMatching: rows.length, returned: Math.min(rows.length, limit), suppliers: rows.slice(0, limit).map(({ _refs, ...r }) => r) };
+  },
+};
+
+const get_supplier = {
+  definition: {
+    name: 'get_supplier',
+    description: 'One supplier / manufacturer in full: the record (kind, country, address, contact), every ingredient it is an approved source for (role supplier/manufacturer, part #, grade, qualification status, primary), every lot received from it (matched by supplier AND by manufacturer), and — with include_trace — the recall trace: the batches that consumed those lots, the finished goods, shipments, samples and sub-batches downstream, plus any lots on hold. Use for "what did we make from supplier X?" and recall questions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Supplier internal id, UID (e.g. SUP-0003), or exact name.' },
+        include_trace: { type: 'boolean', description: 'Add the downstream recall trace (batches, products, shipments, samples). Default true.' },
+      },
+      required: ['id'],
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    let sup = resolveById('suppliers', args.id);
+    if (!sup) { const k = norm(args.id); sup = (db.suppliers || []).find(s => live(s) && norm(s.name) === k) || null; }
+    if (!sup) return { error: `No supplier found for "${args.id}".` };
+    const row = rowOf(db, sup); const refs = row._refs; delete row._refs;
+    const nowMs = Date.now();
+    const sources = refs.sources.map(x => ({ ingredientId: x.ing.id, ingredientUid: x.ing.uid || '', ingredient: x.ing.name || '', role: x.role,
+      partNo: x.src.partNo || '', grade: x.src.grade || '', status: x.src.status || 'qualified', primary: !!x.src.primary, qualifiedDate: x.src.qualifiedDate || null }));
+    const legacyOnly = refs.ingredients.filter(i => !refs.sources.some(x => x.ing.id === i.id)).map(i => ({ ingredientId: i.id, ingredientUid: i.uid || '', ingredient: i.name || '', role: 'supplier', note: 'ingredient supplier field only — no approved-source row' }));
+    const lots = refs.lots.map(({ lot, ing }) => {
+      const days = lot.expiryDate ? Math.floor((Date.parse(lot.expiryDate) - nowMs) / 86400000) : null;
+      return { id: lot.id, uid: lot.uid || '', lotNumber: lot.lotNumber || '', ingredientId: lot.ingredientId, ingredient: ing ? ing.name : '',
+        qtyRemaining: lot.qtyRemaining, qtyReceived: lot.qtyReceived, unit: lot.unit || '', receivedDate: lot.receivedDate || null, expiryDate: lot.expiryDate || null,
+        daysToExpiry: isFinite(days) ? days : null, status: lot.status || 'active', holdReason: lot.holdReason || '', unitCost: (lot.unitCost != null && lot.unitCost !== '') ? lot.unitCost : null, unitCostCcy: lot.unitCostCcy || null };
+    });
+    const out = { supplier: { ...row, address: sup.address || '', notes: sup.notes || '', createdAt: sup.createdAt || null, updatedAt: sup.updatedAt || null }, approvedFor: sources.concat(legacyOnly), lots };
+    if (args.include_trace === false) return out;
+    // Recall trace
+    const moves = db.stockMovements || [];
+    const batchMap = new Map(); const directSamples = [];
+    refs.lots.forEach(({ lot, ing }) => {
+      consumersOfLot(moves, lot.id).forEach(c => {
+        if (c.kind === 'batch' && c.id) {
+          const b = (db.batches || []).find(x => x.id === c.id) || null;
+          if (!batchMap.has(c.id)) {
+            const f = b ? ((db.formulations || []).find(x => x.id === b.formulationId) || null) : null;
+            const ledger = (b && Array.isArray(b.stockLedger)) ? b.stockLedger : [];
+            batchMap.set(c.id, { id: c.id, uid: b ? (b.uid || '') : '', deleted: !b, product: f ? f.name : '', formulationId: b ? b.formulationId : null,
+              preparedDate: b ? (b.preparedDate || null) : null, status: b ? (b.status || '') : '', lotsConsumed: [],
+              shipments: ledger.filter(e => e.kind === 'shipment').map(e => ({ date: e.ts || null, qty: Math.abs(parseFloat(e.delta) || 0), unit: e.unit || (b && b.unit) || '', note: e.note || '' })),
+              samples: b ? (db.samples || []).filter(sm => live(sm) && sm.batchId === b.id).map(sm => ({ id: sm.id, uid: sm.uid || '', name: sm.name || '', status: sm.status || '' })) : [],
+              subBatches: b ? (db.batches || []).filter(x => live(x) && x.parentBatchId === b.id).map(x => ({ id: x.id, uid: x.uid || '', status: x.status || '' })) : [] });
+          }
+          batchMap.get(c.id).lotsConsumed.push({ lotId: lot.id, lotNumber: lot.lotNumber || lot.uid || '', ingredient: ing ? ing.name : '', qty: c.qty, unit: lot.unit || '' });
+        } else if (c.kind === 'sample' && c.id) {
+          const sm = (db.samples || []).find(x => x.id === c.id) || null;
+          directSamples.push({ id: c.id, uid: sm ? (sm.uid || '') : '', name: sm ? (sm.name || '') : '', deleted: !sm, fromLot: lot.lotNumber || lot.uid || '', qty: c.qty, unit: lot.unit || '' });
+        }
+      });
+    });
+    const batches = [...batchMap.values()].sort((a, b) => String(b.preparedDate || '').localeCompare(String(a.preparedDate || '')));
+    const products = []; batches.forEach(x => { if (x.formulationId && !products.some(p => p.formulationId === x.formulationId)) products.push({ formulationId: x.formulationId, product: x.product, batches: batches.filter(y => y.formulationId === x.formulationId).length }); });
+    const held = lots.filter(l => ['hold', 'quarantine', 'rejected'].includes(l.status));
+    out.trace = {
+      summary: { lots: lots.length, lotsOnHand: lots.filter(l => parseFloat(l.qtyRemaining) > 0).length, batches: batches.length, products: products.length,
+        shipments: batches.reduce((n, x) => n + x.shipments.length, 0), samples: batches.reduce((n, x) => n + x.samples.length, 0) + directSamples.length,
+        subBatches: batches.reduce((n, x) => n + x.subBatches.length, 0), lotsOnHold: held.length },
+      recallSignal: held.length ? `${held.length} lot(s) from this supplier are on hold / blocked: ${held.map(l => l.lotNumber || l.uid).join(', ')} — every batch below that consumed them is implicated.` : null,
+      batches, products, directSamples,
+    };
+    return out;
+  },
+};
+
+export const tools = { list_suppliers, get_supplier };