formlab-mcp 0.1.7 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
 [![license](https://img.shields.io/npm/l/formlab-mcp.svg)](https://github.com/juliu1980/FormLab/blob/main/LICENSE)
 [![FormLab](https://img.shields.io/badge/site-formvix.com-2563eb.svg)](https://formvix.com)
 
-A **read-only Model Context Protocol server** for [FormLab](https://formvix.com). Lets Claude (or any MCP-compatible AI assistant) read and analyze your local FormLab database — your formulations, ingredients, batches, samples and test results — **without your data ever leaving your machine**.
+A **read-only Model Context Protocol server** for [FormLab](https://formvix.com). Lets Claude (or any MCP-compatible AI assistant) read and analyze your local FormLab database — your formulations, ingredients, batches, samples and test reports — **without your data ever leaving your machine**.
 
 > Local-first + AI-native. Your proprietary recipes stay on your laptop; only the LLM's answer to your question travels.
 
@@ -32,11 +32,12 @@ 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 / stock / formulations using it. Returns every class-specific sub-object when present: `sequence` (peptide / oligo), `taxon` (NCBI ID + scientific name), `ingredientClass`, `extractDetails`, `sequenceDetails`, `polymerDetails`, `surfactantDetails`, `pigmentDetails`, `fragranceDetails` |
+| `get_ingredient` | Full record + supplier / **cost ($/kg)** / stock / 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` |
 | `list_batches` | Filtered list of production / lab-prep events |
 | `get_batch` | Full record + actual composition + samples + blend lineage |
 | `list_samples` | Filtered list of physical specimens |
-| `get_sample` | Full record + canonical variant + test results + blend lineage |
+| `get_sample` | Full record + canonical variant + test reports + blend lineage |
 | `list_test_results` | Filtered list of test reports |
 | `get_test_result` | Full record + every measurement value |
 | `get_doe_matrix` | Pivot matrix (CSV by default) — rows × ingredients × parameters |
@@ -74,6 +75,29 @@ Requires **Node 18+**.
 
 The MCP server watches the file — re-export from FormLab and the next tool call sees the fresh data without restarting the server.
 
+## Or: LIVE cloud mode (no export needed)
+
+Instead of an export file, point the server at your **live cloud workspace** so it's always current.
+
+1. In FormLab (Pro): **Settings → Account → AI tools (MCP) → Connect…**
+2. Copy the generated config and paste it into Claude Desktop (it merges with the file-mode example below).
+
+The config sets these env vars (which switch the server into cloud mode):
+
+| Env var | Value |
+|---|---|
+| `FORMLAB_SUPABASE_URL` | your Supabase project URL (public) |
+| `FORMLAB_SUPABASE_ANON_KEY` | publishable/anon key (public) |
+| `FORMLAB_REFRESH_TOKEN` | your session refresh token — **a credential** |
+| `FORMLAB_WORKSPACE_ID` | (optional) workspace to read; defaults to your own |
+| `FORMLAB_REFRESH_SECONDS` | (optional) poll interval, default `60` |
+
+When `FORMLAB_REFRESH_TOKEN` + URL + key are present, the server reads the workspace directly (RLS-scoped to you), re-fetching every `FORMLAB_REFRESH_SECONDS`. It's **read-only**.
+
+> ⚠ **Security.** The refresh token grants read access to your account — treat the config like a password (don't share or commit it). To revoke: FormLab → Account → *Sign out of all devices*. A dedicated, revocable, **read-only** MCP token is the planned hardening (needs a small backend: a tokens table + an Edge Function to mint/validate).
+
+Cloud mode needs `@supabase/supabase-js` (a normal dependency) — `npm install` in this folder, or `npx -y formlab-mcp` pulls it automatically.
+
 ## Wire it up to Claude Desktop
 
 Add this to your `claude_desktop_config.json` (on macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
@@ -105,7 +129,7 @@ Or for local-dev (from the repo):
 }
 ```
 
-Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 15 tools become callable in any conversation.
+Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 17 tools become callable in any conversation.
 
 ## Wire it up to Claude Code
 

package/cloud.js

@@ -0,0 +1,114 @@
+// ============================================================
+// CLOUD MODE — read the LIVE FormLab workspace from Supabase instead of a
+// static export file. The tools are unchanged: we assemble the same `db` shape
+// (each synced table stores the full record in a `data` JSONB column) and set it
+// via data.js setStoreFromDb, then re-fetch on an interval so it stays "live".
+//
+// v1 auth: the user's session REFRESH TOKEN (from FormLab's "Connect to MCP"
+// panel). Read-only by usage; RLS scopes every query to the user's own
+// workspaces. The refresh token is the full account session, though — a
+// dedicated, revocable, read-only MCP token is the planned hardening (needs a
+// small backend: a tokens table + an Edge Function to mint/validate).
+// ============================================================
+
+import { createClient } from '@supabase/supabase-js';
+import { setStoreFromDb } from './data.js';
+
+// Supabase table → db array key (mirrors the app's ENT.ENTITIES + db.js arrays).
+// Safety/regulatory ride the ingredient record's `data`, so they come for free.
+const TABLES = [
+  ['projects',            'projects'],
+  ['ingredients',         'ingredients'],
+  ['formulations',        'formulations'],
+  ['batches',             'batches'],
+  ['samples',             'samples'],
+  ['test_results',        'testResults'],
+  ['templates',           'templates'],
+  ['procedure_templates', 'procedureTemplates'],
+  ['parameters',          'parameters'],
+  ['equipment',           'equipment'],
+  ['stock_movements',     'stockMovements'],
+  ['lots',                'lots'],
+  ['formula_versions',    'formulaVersions'],
+  ['attachments',         'attachments'],
+  ['notebook_entries',    'notebookEntries'],
+];
+
+const PAGE = 1000;
+
+async function _fetchAll(supabase, table, workspaceId) {
+  const out = [];
+  for (let from = 0; ; from += PAGE) {
+    const { data, error } = await supabase
+      .from(table)
+      .select('data')
+      .eq('workspace_id', workspaceId)
+      .is('deleted_at', null)
+      .range(from, from + PAGE - 1);
+    if (error) {
+      // A table the backend hasn't migrated yet shouldn't sink the whole load.
+      if (/relation|does not exist|schema cache|find the table/i.test(error.message || '')) return out;
+      throw new Error(`${table}: ${error.message}`);
+    }
+    const rows = data || [];
+    for (const r of rows) if (r && r.data) out.push(r.data);
+    if (rows.length < PAGE) break;
+  }
+  return out;
+}
+
+async function _resolveWorkspace(supabase, userId, preferred) {
+  if (preferred) return preferred;
+  const { data, error } = await supabase
+    .from('workspace_members')
+    .select('workspace_id, role')
+    .eq('user_id', userId);
+  if (error) throw new Error(`workspace_members: ${error.message}`);
+  const rows = data || [];
+  if (!rows.length) throw new Error('No workspaces found for this account.');
+  const owned = rows.find(r => r.role === 'owner');
+  return (owned || rows[0]).workspace_id;   // default to your OWN workspace
+}
+
+async function _loadDb(supabase, workspaceId) {
+  const db = {};
+  for (const [table, key] of TABLES) db[key] = await _fetchAll(supabase, table, workspaceId);
+  return db;
+}
+
+// Bootstrap a session from the refresh token, do an initial load, then refresh on
+// an interval. Returns { workspaceId, userId, refresh, stop }.
+export async function startCloud({ url, anonKey, refreshToken, workspaceId, refreshSeconds = 60, onReload } = {}) {
+  if (!url || !anonKey || !refreshToken) {
+    throw new Error('Cloud mode needs FORMLAB_SUPABASE_URL, FORMLAB_SUPABASE_ANON_KEY and FORMLAB_REFRESH_TOKEN (copy them from FormLab → Connect to MCP).');
+  }
+  const supabase = createClient(url, anonKey, {
+    auth: { persistSession: false, autoRefreshToken: true, detectSessionInUrl: false },
+  });
+  // refreshSession with a bare refresh token mints a fresh session and sets it on
+  // the client, so all subsequent queries carry the user's JWT (→ RLS).
+  const { data: sess, error: sErr } = await supabase.auth.refreshSession({ refresh_token: refreshToken });
+  if (sErr || !(sess && sess.session && sess.session.user)) {
+    throw new Error(`auth failed: ${(sErr && sErr.message) || 'could not start a session from the refresh token — it may have expired; reconnect from FormLab.'}`);
+  }
+  const userId = sess.session.user.id;
+  const ws = await _resolveWorkspace(supabase, userId, workspaceId);
+
+  const refresh = async () => {
+    const db = await _loadDb(supabase, ws);
+    setStoreFromDb(db, { source: 'cloud', workspaceId: ws, schemaName: 'formlab-live', loadedAt: new Date().toISOString() });
+    if (onReload) { try { onReload(db); } catch (_) {} }
+    return db;
+  };
+
+  await refresh();   // initial synchronous load before tools accept calls
+
+  let timer = null;
+  if (refreshSeconds > 0) {
+    timer = setInterval(() => {
+      refresh().catch(e => process.stderr.write(`[formlab-mcp] cloud refresh failed: ${e.message}\n`));
+    }, refreshSeconds * 1000);
+    if (timer.unref) timer.unref();   // don't keep the process alive just for the timer
+  }
+  return { workspaceId: ws, userId, refresh, stop: () => { if (timer) clearInterval(timer); } };
+}

package/data.js

@@ -43,6 +43,20 @@ export function getStore() {
   return _store;
 }
 
+// Set the store directly from an in-memory db object (used by cloud mode — see
+// cloud.js). Produces the SAME store shape as loadStore(), so every tool works
+// identically whether the data came from an export file or the live workspace.
+export function setStoreFromDb(db, meta) {
+  _store = {
+    db: db || {},
+    meta: meta || null,
+    loadedAt: new Date().toISOString(),
+    sourcePath: (meta && meta.source) || 'cloud',
+    indexes: _buildIndexes(db || {}),
+  };
+  return _store;
+}
+
 // Re-read the file on disk-change. Useful when the user re-exports
 // FormLab while the MCP server is running — the next tool call sees
 // fresh data without restarting the server.

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 13 tools (see ./tools/) over stdio. The MCP host (Claude
+// Exposes 17 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.
@@ -25,53 +25,77 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 
 import { loadStore, watchStore, getStore } from './data.js';
+import { startCloud } from './cloud.js';
 import * as formulations from './tools/formulations.js';
 import * as ingredients  from './tools/ingredients.js';
 import * as lab          from './tools/lab.js';
 import * as analytics    from './tools/analytics.js';
 
-const filePath = process.argv[2] || process.env.FORMLAB_EXPORT;
-if (!filePath) {
+// ----- Data source: LIVE cloud workspace OR a static export file -----
+// Cloud mode kicks in when the Supabase env vars are present (copy them from
+// FormLab → Connect to MCP). Otherwise we fall back to the export-file mode.
+const CLOUD = process.env.FORMLAB_REFRESH_TOKEN && process.env.FORMLAB_SUPABASE_URL && process.env.FORMLAB_SUPABASE_ANON_KEY;
+
+if (CLOUD) {
+  try {
+    const h = await startCloud({
+      url:           process.env.FORMLAB_SUPABASE_URL,
+      anonKey:       process.env.FORMLAB_SUPABASE_ANON_KEY,
+      refreshToken:  process.env.FORMLAB_REFRESH_TOKEN,
+      workspaceId:   process.env.FORMLAB_WORKSPACE_ID || null,
+      refreshSeconds: Number(process.env.FORMLAB_REFRESH_SECONDS || 60),
+    });
+    const s = getStore();
+    process.stderr.write(
+      `[formlab-mcp] LIVE cloud mode · workspace ${h.workspaceId} · ` +
+      `${(s.db.ingredients||[]).length} ingredients · ${(s.db.formulations||[]).length} formulas · ` +
+      `refresh every ${Number(process.env.FORMLAB_REFRESH_SECONDS || 60)}s\n`);
+  } catch (e) {
+    process.stderr.write(`[formlab-mcp] cloud mode failed: ${e.message}\n`);
+    process.exit(1);
+  }
+} else {
+  const filePath = process.argv[2] || process.env.FORMLAB_EXPORT;
+  if (!filePath) {
+    process.stderr.write([
+      'Usage: formlab-mcp <path-to-export.json>           (file mode)',
+      '   or: set FORMLAB_SUPABASE_URL / FORMLAB_SUPABASE_ANON_KEY /',
+      '       FORMLAB_REFRESH_TOKEN (+ optional FORMLAB_WORKSPACE_ID)   (LIVE cloud mode)',
+      '',
+      'File mode: export via Settings → Import / Export → Export.',
+      'Cloud mode: copy the values from FormLab → Connect to MCP.',
+      '',
+    ].join('\n'));
+    process.exit(1);
+  }
+  try {
+    loadStore(filePath);
+  } catch (e) {
+    process.stderr.write(`[formlab-mcp] failed to load export: ${e.message}\n`);
+    process.exit(1);
+  }
+  const store = getStore();
   process.stderr.write([
-    'Usage: formlab-mcp <path-to-export.json>',
-    'Or set FORMLAB_EXPORT=<path> and call without args.',
-    '',
-    'Export your FormLab database via Settings → Import / Export → Export,',
-    'then point this server at the downloaded formlab-export-YYYY-MM-DD.json.',
+    `[formlab-mcp] loaded ${store.sourcePath}`,
+    store.meta
+      ? `  schema=${store.meta.schemaName} v${store.meta.schemaVersion} exportedAt=${store.meta.exportedAt}`
+      : `  (legacy bare-db shape — no FAIR metadata)`,
+    `  records: ${
+      [
+        `${(store.db.ingredients  || []).length} ingredients`,
+        `${(store.db.formulations || []).length} formulas`,
+        `${(store.db.batches      || []).length} batches`,
+        `${(store.db.samples      || []).length} samples`,
+        `${(store.db.testResults  || []).length} test results`,
+      ].join(' · ')
+    }`,
     '',
   ].join('\n'));
-  process.exit(1);
-}
-
-try {
-  loadStore(filePath);
-} catch (e) {
-  process.stderr.write(`[formlab-mcp] failed to load export: ${e.message}\n`);
-  process.exit(1);
+  watchStore((s) => {
+    process.stderr.write(`[formlab-mcp] reloaded — ${(s.db.formulations||[]).length} formulas now\n`);
+  });
 }
 
-const store = getStore();
-process.stderr.write([
-  `[formlab-mcp] loaded ${store.sourcePath}`,
-  store.meta
-    ? `  schema=${store.meta.schemaName} v${store.meta.schemaVersion} exportedAt=${store.meta.exportedAt}`
-    : `  (legacy bare-db shape — no FAIR metadata)`,
-  `  records: ${
-    [
-      `${(store.db.ingredients  || []).length} ingredients`,
-      `${(store.db.formulations || []).length} formulas`,
-      `${(store.db.batches      || []).length} batches`,
-      `${(store.db.samples      || []).length} samples`,
-      `${(store.db.testResults  || []).length} test results`,
-    ].join(' · ')
-  }`,
-  '',
-].join('\n'));
-
-watchStore((s) => {
-  process.stderr.write(`[formlab-mcp] reloaded — ${(s.db.formulations||[]).length} formulas now\n`);
-});
-
 // All tools live in tools/*.js as a flat { definition, handler } pair.
 // Concatenate the four modules' exports into a single registry the
 // MCP server can use for both list_tools and call_tool dispatch.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "formlab-mcp",
-  "version": "0.1.7",
+  "version": "0.3.0",
   "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 local FormLab export. Your recipes never leave your machine.",
+  "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",
   "bin": {
     "formlab-mcp": "./index.js"
@@ -16,7 +16,8 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4"
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@supabase/supabase-js": "^2.45.0"
   },
   "optionalDependencies": {
     "@rdkit/rdkit": "^2024.9.1"

package/tools/ingredients.js

@@ -6,19 +6,52 @@
 
 import { getStore, resolveById } from '../data.js';
 
+// FormLab's export is the raw db, so ingredients carry the APP field shapes:
+// `cas` (not casNumber) and `cost = {value, currency, unit}` (not a flat
+// costPerKg). Normalize here so the tools surface usable values instead of nulls.
+const _MASS_TO_KG = { kg: 1, g: 0.001, mg: 0.000001, t: 1000, lb: 0.45359237, oz: 0.028349523 };
+const _VOL_TO_L  = { l: 1, ml: 0.001, gal: 3.785411784, qt: 0.946352946 };
+
+function _densityKgPerL(i) {
+  if (!i || i.density == null) return null;
+  const d = Number(i.density); if (!isFinite(d) || d <= 0) return null;
+  const u = String(i.densityUnit || 'kg/L').toLowerCase().replace(/\s/g, '');
+  if (u === 'kg/m3' || u === 'kg/m³') return d / 1000;
+  if (u === 'lb/gal') return d * 0.1198264;
+  return d; // kg/L, g/mL, g/cm³ are numerically equal to kg/L
+}
+
+// Cost normalized to currency-per-kg from ing.cost {value, currency, unit}.
+// Mass units convert directly; volumetric units need density; counts → null.
+function _costPerKg(i) {
+  const c = i && i.cost;
+  if (!c || c.value == null || c.value === '') return null;
+  const v = Number(c.value); if (!isFinite(v)) return null;
+  const unit = String(c.unit || 'kg').toLowerCase();
+  if (_MASS_TO_KG[unit] != null) return +(v / _MASS_TO_KG[unit]).toFixed(6);
+  if (_VOL_TO_L[unit] != null) {
+    const dens = _densityKgPerL(i);
+    return dens ? +((v / _VOL_TO_L[unit]) / dens).toFixed(6) : null;
+  }
+  return null;
+}
+
 function _trimIngredient(i) {
   if (!i) return null;
+  const cost = i.cost || null;
   return {
     id: i.id,
     uid: i.uid,
     name: i.name,
     family: i.family || '',
     supplier: i.supplier || '',
-    casNumber: i.casNumber || '',
+    casNumber: i.cas || i.casNumber || '',
     density: i.density != null ? i.density : null,
     densityUnit: i.densityUnit || (i.density != null ? 'kg/L' : null),
-    costPerKg: i.costPerKg != null ? i.costPerKg : null,
-    costCurrency: i.costCurrency || (i.costPerKg != null ? 'USD' : null),
+    cost: (cost && cost.value != null && cost.value !== '')
+      ? { value: cost.value, currency: cost.currency || 'USD', unit: cost.unit || 'kg' } : null,
+    costPerKg: _costPerKg(i),
+    costCurrency: (cost && cost.currency) || null,
     stockOnHand: i.stockOnHand != null ? i.stockOnHand : null,
     stockUnit: i.stockUnit || null,
     // Tier 1 expansion fields — keep optional so legacy exports stay clean.
@@ -88,7 +121,7 @@ const list_ingredients = {
 const get_ingredient = {
   definition: {
     name: 'get_ingredient',
-    description: 'Get full details for a single ingredient including stock movements, formulations using it, and stock-on-hand. 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, inventory lots (balances + expiry), recent stock movements, and the formulations using it. Accepts internal id or UID (e.g. ING-001).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -107,18 +140,42 @@ const get_ingredient = {
     const usedIn = (db.formulations || []).filter(f =>
       f && !f._trashed && (f.composition || []).some(c => c && c.ingredientId === ing.id)
     ).map(f => ({ id: f.id, uid: f.uid, name: f.name }));
-    const movements = (ing.stockMovements || []).slice(-20).map(m => ({
-      ts: m.ts,
-      reason: m.reason,
-      delta: m.delta,
-      unit: m.unit,
-      note: m.note || '',
-    }));
+    // Stock movements live in the top-level db.stockMovements ledger (each tagged
+    // with ingredientId + an `at` timestamp), NOT on the ingredient record.
+    const movements = (db.stockMovements || [])
+      .filter(m => m && m.ingredientId === ing.id)
+      .slice(-20)
+      .map(m => ({ ts: m.at || m.ts || null, reason: m.reason, delta: m.delta, unit: m.unit, lotId: m.lotId || null, note: m.note || '' }));
+    // GHS safety summary (pictograms / H- / P-codes / signal word).
+    const safety = ing.safety ? {
+      signalWord: ing.safety.signalWord || null,
+      pictograms: ing.safety.pictograms || [],
+      hazardStatements: ing.safety.hazardStatements || [],
+      precautionaryStatements: ing.safety.precautionaryStatements || [],
+      source: ing.safety.source || null,
+    } : null;
+    // Per-jurisdiction regulatory status (+ provenance + last-checked date).
+    const regulatory = Array.isArray(ing.regulatory) ? ing.regulatory.map(r => ({
+      jurisdiction: r.jurisdiction, status: r.status, note: r.note || '',
+      source: r.source || 'manual', checkedDate: r.checkedDate || null,
+    })) : [];
+    // Inventory lots for this ingredient (balances + expiry + traceability).
+    const lots = (db.lots || [])
+      .filter(l => l && l.ingredientId === ing.id)
+      .map(l => ({
+        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',
+      }));
     return {
       ..._trimIngredient(ing),
       description: ing.description || '',
       notes: ing.notes || '',
       attributes: ing.attributes || {},
+      safety,
+      regulatory,
+      lots,
       formulationCount: usedIn.length,
       formulations: usedIn.slice(0, 30),
       recentStockMovements: movements,
@@ -221,4 +278,54 @@ const find_by_smarts = {
   },
 };
 
-export const tools = { list_ingredients, get_ingredient, find_by_smarts };
+// =====================================================================
+// list_lots — inventory lots across ingredients (Tier 3). Each lot is a
+// received batch of one ingredient with its own remaining balance, supplier,
+// and expiry. Filter by ingredient, expiring-soon, or status.
+// =====================================================================
+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.',
+    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").' },
+        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));
+    let ing = null;
+    if (args.ingredient_id) {
+      ing = resolveById('ingredients', args.ingredient_id);
+      if (!ing) return { error: `No ingredient found for id "${args.ingredient_id}".` };
+    }
+    const nameById = new Map((db.ingredients || []).map(i => [i.id, i.name]));
+    const nowMs = Date.now();
+    const rows = (db.lots || []).filter(l => {
+      if (!l || l._trashed) return false;
+      if (ing && l.ingredientId !== ing.id) return false;
+      if (args.status && String(l.status || 'active').toLowerCase() !== String(args.status).toLowerCase()) return false;
+      if (args.expiring_within_days != null) {
+        if (!l.expiryDate) return false;
+        const days = Math.floor((Date.parse(l.expiryDate) - nowMs) / 86400000);
+        if (!(isFinite(days) && days <= args.expiring_within_days)) return false;
+      }
+      return true;
+    }).map(l => ({
+      id: l.id, uid: l.uid, lotNumber: l.lotNumber || '',
+      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',
+    }));
+    return { totalMatching: rows.length, returned: Math.min(rows.length, limit), lots: rows.slice(0, limit) };
+  },
+};
+
+export const tools = { list_ingredients, get_ingredient, find_by_smarts, list_lots };