formlab-mcp 0.6.21 → 0.6.23

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) |
@@ -54,13 +56,13 @@ Ask Claude (or another MCP client) things like:
 | `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 |
 | `find_by_smarts` | SMARTS-pattern substructure search across every ingredient with a SMILES. Requires `@rdkit/rdkit` (optional dependency — install with `npm install @rdkit/rdkit` in `mcp/` if you get a "not installed" error). Examples: `c1ccccc1` (any aromatic 6-ring), `[OX2H1]` (any hydroxyl), `C(=O)O` (carboxylic acid), `[F,Cl,Br,I]` (any halogen). |
 | `list_equipment` | Filtered list of the Equipment registry (mixers, ovens, viscometers, balances…). Filters: `category`, `status`, `manufacturer`, `name_contains` |
-| `get_equipment` | Full equipment record + a summary of where it's used (panels, step presets, test methods, formulas, batches) |
+| `get_equipment` | Full equipment record + `usedIn` (panels, step presets, test methods, formula steps, batches, testReports resolved to it), `usage` (reports / formulas / batches / samples / pass rate / top formulas) and `measured` (per parameter: mean here vs mean on other instruments, biasPct) |
 | `list_test_methods` | Filtered list of Test Methods (the parameter library). Filter by `analyte` (the property measured, e.g. `Viscosity` — finds every method for it), `category`, `name_contains`, `include_retired` |
-| `get_test_method` | Full method definition (SOP / sample prep / equipment / calculation / acceptance spec) + sibling methods sharing its analyte |
+| `get_test_method` | One Test Method: full definition, run conditions, analyte siblings, using panels, plus `usage`, `valueSummary` (mean / sd / min / max) and `byInstrument` |
 | `list_step_presets` | Filtered list of Step Presets (reusable procedure steps: duration / temp / RPM / equipment). Filters: `industry`, `name_contains` |
 | `get_step_preset` | Full step-preset record incl. the multi-value equipment list (`{name, equipmentId}`) |
 | `list_test_panels` | Filtered list of Test Panels (reusable column-sets — the parameters measured together on a sample). Filters: `industry`, `name_contains` |
-| `get_test_panel` | Full panel record — ordered parameter list (each with resolved Test Method UID, unit, spec) + instruments |
+| `get_test_panel` | One Test Panel: ordered parameters with resolved method UIDs + specs, plus `usage` (reports created from it) and `performanceByParameter` |
 | `list_projects` | Filtered list of projects (the buckets formulations are filed under) + per-project formulation count. Filters: `status`, `name_contains` |
 | `get_project` | Full project record + the formulations filed under it |
 | `list_notebook_entries` | ELN feed — dated authored notes attached to records. Filters: `entity_type`, `entity_id`, `author`, `text_contains`, `since`, `until` |
@@ -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,8 +1,8 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.21",
+  "version": "0.6.23",
   "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.",
+  "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",
   "bin": {
     "formlab-mcp": "./index.js"

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.21",
+  "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.21",
+      "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/analytics.js

@@ -913,6 +913,7 @@ const get_stability = {
   },
 };
 
+export { _evalPassFail };
 export const tools = {
   list_test_results,
   get_test_result,

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,
     })) } : {}),
@@ -96,7 +97,7 @@ function _lotSourceInfo(l) {
   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 = {
@@ -197,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 {
@@ -354,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/library.js

@@ -12,6 +12,55 @@
 // ============================================================
 
 import { getStore, resolveById } from '../data.js';
+import { _evalPassFail } from './analytics.js';
+
+// ── Usage roll-ups (mirror the Usage tabs on the Panel / Method / Equipment
+//    detail pages) ────────────────────────────────────────────────────────
+// Resolve a measurement's instrument the way the app does: named on the row →
+// the parameter's Test Method equipment → the report's run default.
+function _resolveInstrument(m, t, db) {
+  if (m.equipmentId || m.instrument) return { equipmentId: m.equipmentId || '', name: m.instrument || '', source: 'row' };
+  const pm = m.parameterId ? (db.parameters || []).find(p => p.id === m.parameterId)
+    : (db.parameters || []).find(p => _norm(p.name) === _norm(m.parameter));
+  if (pm && (pm.equipmentId || pm.equipment)) return { equipmentId: pm.equipmentId || '', name: pm.equipment || '', source: 'method' };
+  if (t && (t.equipmentId || t.instrument)) return { equipmentId: t.equipmentId || '', name: t.instrument || '', source: 'run' };
+  return { equipmentId: '', name: '', source: '' };
+}
+function _num(m) { const v = parseFloat(m && m.value); return Number.isFinite(v) ? v : null; }
+function _mean(a) { return a.length ? a.reduce((x, y) => x + y, 0) / a.length : null; }
+function _sd(a) { if (a.length < 2) return null; const mu = _mean(a); return Math.sqrt(a.reduce((acc, x) => acc + (x - mu) ** 2, 0) / (a.length - 1)); }
+function _r(v, d = 3) { return v == null ? null : +v.toFixed(d); }
+// Where a set of reports (optionally restricted to measurements passing
+// `measFilter`) landed: totals + by-formula breakdown (top 10). `fails` uses the
+// measurement's own acceptance criteria (panel spec inheritance is app-side).
+function _usageRollup(db, tests, measFilter) {
+  const sById = new Map((db.samples || []).map(s => [s.id, s]));
+  const bById = new Map((db.batches || []).map(b => [b.id, b]));
+  const fById = new Map((db.formulations || []).map(f => [f.id, f]));
+  const date = t => String(t.testDate || (t.createdAt || '').slice(0, 10) || '');
+  const byF = new Map(); const forms = new Set(), batches = new Set(), samples = new Set(), labs = new Set();
+  let readings = 0, fails = 0, withSpec = 0, last = '';
+  tests.forEach(t => {
+    const s = sById.get(t.sampleId) || null; const b = s ? bById.get(s.batchId) : null;
+    const f = (s && s.formulationId) ? fById.get(s.formulationId) : (b ? fById.get(b.formulationId) : null);
+    if (s) samples.add(s.id); if (b) batches.add(b.id); if (f) forms.add(f.id); if (t.lab) labs.add(t.lab);
+    const d = date(t); if (d > last) last = d;
+    let tf = 0;
+    (t.measurements || []).filter(m => !measFilter || measFilter(m, t)).forEach(m => {
+      readings++;
+      const pf = _evalPassFail(m); if (pf !== 'no-criteria' && pf !== 'untested') withSpec++; if (pf === 'fail') { fails++; tf++; }
+    });
+    const key = f ? f.id : '(no formula)';
+    if (!byF.has(key)) byF.set(key, { formula: f ? (f.uid || f.name) : null, formulaName: f ? f.name : null, reports: 0, lastRun: '', fails: 0 });
+    const g = byF.get(key); g.reports++; if (d > g.lastRun) g.lastRun = d; g.fails += tf;
+  });
+  return {
+    reports: tests.length, readings, lastUsed: last || null,
+    formulas: forms.size, batches: batches.size, samples: samples.size, labs: labs.size,
+    fails, passRate: withSpec ? _r(100 * (withSpec - fails) / withSpec, 0) : null,
+    byFormula: [...byF.values()].sort((a, b) => b.reports - a.reports).slice(0, 10),
+  };
+}
 
 const _norm = (s) => String(s == null ? '' : s).toLowerCase();
 const _clampLimit = (n) => Math.min(1000, Math.max(1, n || 100));
@@ -99,7 +148,7 @@ const list_equipment = {
 const get_equipment = {
   definition: {
     name: 'get_equipment',
-    description: 'Get one equipment record by UID (e.g. EQP-001) or id, including a summary of everywhere it is referenced (test panels, step presets, test methods, formulas, batches).',
+    description: 'Get one equipment record by UID (e.g. EQP-001) or id, including `usedIn` (everywhere its DEFINITION is referenced: test panels, step presets, test methods, formula steps, batches, plus testReports = reports with a measurement resolved to it), `usage` (those reports: totals, last used, distinct formulas/batches/samples, pass rate, top formulas) and `measured` (per parameter: readings and mean on this unit vs readings/mean on all OTHER instruments, with biasPct — the calibration question). Instrument resolution follows the app: named on the measurement → the Test Method\'s equipment → the report\'s run default.',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Equipment UID or internal id.' } },
@@ -110,7 +159,25 @@ const get_equipment = {
     const { db } = getStore();
     const e = resolveById('equipment', args.id);
     if (!e) return { error: `No equipment found for "${args.id}".` };
-    return { ...(_trimEquipment(e)), usedIn: _equipUsage(e, db) };
+    // Measurements whose RESOLVED instrument is this unit (row → method → run).
+    const nm = _norm(e.name);
+    const mine = (m, t) => { const r = _resolveInstrument(m, t, db); return r.equipmentId ? r.equipmentId === e.id : (!!nm && _norm(r.name) === nm); };
+    const tests = (db.testResults || []).filter(t => (t.measurements || []).some(m => mine(m, t)));
+    const here = new Map(), fleet = new Map();
+    (db.testResults || []).forEach(t => (t.measurements || []).forEach(m => {
+      const pn = (m.parameter || '').trim(); if (!pn) return;
+      const v = _num(m); const isMine = mine(m, t); const bucket = isMine ? here : fleet;
+      if (!bucket.has(pn)) bucket.set(pn, { parameter: pn, readings: 0, vals: [], fails: 0 });
+      const g = bucket.get(pn); g.readings++; if (v != null) g.vals.push(v); if (isMine && _evalPassFail(m) === 'fail') g.fails++;
+    }));
+    const measured = [...here.values()].map(g => {
+      const f = fleet.get(g.parameter); const mh = _mean(g.vals), me = f ? _mean(f.vals) : null;
+      return { parameter: g.parameter, readings: g.readings, mean: _r(mh), fails: g.fails, readingsElsewhere: f ? f.readings : 0, meanElsewhere: _r(me),
+        biasPct: (mh != null && me != null && me !== 0) ? _r((mh - me) / Math.abs(me) * 100, 1) : null };
+    }).sort((a, b) => b.readings - a.readings);
+    const usedIn = _equipUsage(e, db);
+    usedIn.testReports = tests.length;
+    return { ...(_trimEquipment(e)), usedIn, usage: _usageRollup(db, tests, mine), measured };
   },
 };
 
@@ -187,7 +254,7 @@ const list_test_methods = {
 const get_test_method = {
   definition: {
     name: 'get_test_method',
-    description: 'Get one Test Method by UID (e.g. PARAM-001) or id — full definition including SOP / sample prep / equipment / calculation / acceptance spec, the declared runConditions this method varies by (the vocabulary — e.g. Storage temp/RH, spindle RPM; each measurement captures a value per condition), plus sibling methods that share its analyte (the same property measured at other conditions) and the Test Panels that use this method.',
+    description: 'Get one Test Method by UID (e.g. PARAM-001) or id — full definition including SOP / sample prep / equipment / calculation / acceptance spec, the declared runConditions this method varies by (the vocabulary — e.g. Storage temp/RH, spindle RPM; each measurement captures a value per condition), sibling methods that share its analyte, the Test Panels that use it, plus `usage` (reports / readings linked to this method: totals, last used, distinct formulas/batches/samples, pass rate, top formulas), `valueSummary` (mean / sd / min / max over numeric readings) and `byInstrument` (readings, mean and fails per resolved instrument — a mean that differs between units is a calibration question).',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Test Method UID or internal id.' } },
@@ -208,7 +275,19 @@ const get_test_method = {
       (row.parameterId && row.parameterId === p.id) ||
       (!row.parameterId && _norm(row.parameter || row.name) === nm)
     )).map(t => t.uid || t.name).slice(0, 40);
-    return { ...(_trimMethod(p, { full: true })), analyteSiblings: siblings, usingPanels };
+    // Usage = every measurement linked to this method (by id, else by exact name).
+    const match = (m) => (m.parameterId && m.parameterId === p.id) || (!m.parameterId && _norm(m.parameter) === nm);
+    const tests = (db.testResults || []).filter(r => (r.measurements || []).some(match));
+    const vals = [], byInst = new Map();
+    tests.forEach(r => (r.measurements || []).filter(match).forEach(m => {
+      const v = _num(m); if (v != null) vals.push(v);
+      const inst = _resolveInstrument(m, r, db); const key = inst.name || inst.equipmentId || '(unresolved)';
+      if (!byInst.has(key)) byInst.set(key, { instrument: key, readings: 0, vals: [], fails: 0 });
+      const g = byInst.get(key); g.readings++; if (v != null) g.vals.push(v); if (_evalPassFail(m) === 'fail') g.fails++;
+    }));
+    const byInstrument = [...byInst.values()].map(g => ({ instrument: g.instrument, readings: g.readings, mean: _r(_mean(g.vals)), fails: g.fails })).sort((a, b) => b.readings - a.readings);
+    const valueSummary = { readings: vals.length, mean: _r(_mean(vals)), sd: _r(_sd(vals)), min: vals.length ? Math.min(...vals) : null, max: vals.length ? Math.max(...vals) : null, unit: p.defaultUnit || '' };
+    return { ...(_trimMethod(p, { full: true })), analyteSiblings: siblings, usingPanels, usage: _usageRollup(db, tests, match), valueSummary, byInstrument };
   },
 };
 
@@ -356,7 +435,7 @@ const list_test_panels = {
 const get_test_panel = {
   definition: {
     name: 'get_test_panel',
-    description: 'Get one Test Panel by UID (e.g. TMPL-001) or id — full ordered parameter list (each with its resolved Test Method UID, unit, and spec), instruments, and notes.',
+    description: 'Get one Test Panel by UID (e.g. TMPL-001) or id — full ordered parameter list (each with its resolved Test Method UID, unit, and spec), instruments, notes, plus `usage` (reports created from this panel: totals, last used, distinct formulas/batches/samples, pass rate, top formulas) and `performanceByParameter` (readings / fails per parameter). Usage counts reports created from the panel, not parameter overlap.',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Test Panel UID or internal id.' } },
@@ -367,7 +446,19 @@ const get_test_panel = {
     const { db } = getStore();
     const t = resolveById('templates', args.id);
     if (!t) return { error: `No test panel found for "${args.id}".` };
-    return _trimPanel(t, db, { full: true });
+    // Usage = reports created FROM this panel (templateId) — not parameter overlap.
+    const tests = (db.testResults || []).filter(r => r.templateId === t.id);
+    const perf = (t.parameters || []).map(row => {
+      const nm = _norm(row.parameter || row.name), pid = row.parameterId || '';
+      let n = 0, fails = 0, withSpec = 0;
+      tests.forEach(r => (r.measurements || []).forEach(m => {
+        const hit = (pid && m.parameterId === pid) || ((!m.parameterId || !pid) && _norm(m.parameter) === nm);
+        if (!hit) return; n++;
+        const pf = _evalPassFail(m); if (pf !== 'no-criteria' && pf !== 'untested') withSpec++; if (pf === 'fail') fails++;
+      }));
+      return { parameter: row.parameter || row.name, readings: n, fails, failRatePct: withSpec ? _r(100 * fails / withSpec, 0) : null };
+    });
+    return { ...(_trimPanel(t, db, { full: true })), usage: _usageRollup(db, tests, null), performanceByParameter: perf };
   },
 };
 

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 };