formlab-mcp 0.1.7 → 0.4.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,17 +32,31 @@ 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_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 + 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 |
 | `find_failures` | Pareto-style: parameters that fail acceptance most often |
 | `get_coverage_matrix` | Which formulations × parameters have been measured |
 | `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) |
+| `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 |
+| `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 |
+| `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` |
+| `get_notebook_entry` | One notebook entry — full body, author, attachment metadata, resolved linked record |
 
 ## Install
 
@@ -74,6 +88,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 +142,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 30 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 30 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,65 +25,95 @@ 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';
+import * as library      from './tools/library.js';
+import * as projects     from './tools/projects.js';
+import * as notebook     from './tools/notebook.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.
+// Concatenate every module's exports into a single registry the MCP
+// server can use for both list_tools and call_tool dispatch.
 const TOOLS = [
   ...Object.values(formulations.tools),
   ...Object.values(ingredients.tools),
   ...Object.values(lab.tools),
   ...Object.values(analytics.tools),
+  ...Object.values(library.tools),
+  ...Object.values(projects.tools),
+  ...Object.values(notebook.tools),
 ];
 
 const server = new Server(
-  { name: 'formlab-mcp', version: '0.1.0' },
+  { name: 'formlab-mcp', version: '0.4.0' },
   { capabilities: { tools: {} } }
 );
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "formlab-mcp",
-  "version": "0.1.7",
+  "version": "0.4.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,131 @@ 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) };
+  },
+};
+
+// =====================================================================
+// list_inventory — portfolio stock view. One row per ingredient rolling
+// up on-hand quantity, lot balances, nearest expiry, and a low-stock flag
+// (stockOnHand at/below its reorderThreshold, or zero). Answers "what's
+// low / expiring / out" across the whole library in a single call —
+// list_lots is per-lot and get_ingredient is one ingredient at a time.
+// =====================================================================
+const list_inventory = {
+  definition: {
+    name: 'list_inventory',
+    description: 'Portfolio inventory status — one row per ingredient with on-hand quantity, summed lot balance, lot count, nearest lot expiry, and a low-stock flag (on-hand at/below its reorder threshold, or zero). Filter to low-stock or expiring items. Sorted low-stock first, then by on-hand ascending.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        low_stock_only: { type: 'boolean', description: 'Only ingredients flagged low (on-hand ≤ reorderThreshold, or on-hand is 0).' },
+        expiring_within_days: { type: 'number', description: 'Only ingredients with a lot expiring within this many days from now (already-expired lots always qualify).' },
+        family: { type: 'string', description: 'Filter by ingredient family. Case-insensitive substring.' },
+        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 norm = (s) => String(s || '').toLowerCase();
+    const nowMs = Date.now();
+    // Group lots by ingredient once (avoids an O(n²) scan per ingredient).
+    const lotsByIng = new Map();
+    (db.lots || []).forEach(l => {
+      if (!l || l._trashed || !l.ingredientId) return;
+      if (!lotsByIng.has(l.ingredientId)) lotsByIng.set(l.ingredientId, []);
+      lotsByIng.get(l.ingredientId).push(l);
+    });
+    const rows = (db.ingredients || []).filter(i => {
+      if (!i || i._trashed) return false;
+      if (args.family && !norm(i.family).includes(norm(args.family))) return false;
+      return true;
+    }).map(i => {
+      const lots = lotsByIng.get(i.id) || [];
+      const onHand = i.stockOnHand != null ? Number(i.stockOnHand) : null;
+      const reorder = i.reorderThreshold != null ? Number(i.reorderThreshold) : null;
+      const lotBalance = lots.reduce((s, l) => s + (isFinite(Number(l.qtyRemaining)) ? Number(l.qtyRemaining) : 0), 0);
+      const expiries = lots.map(l => Date.parse(l.expiryDate)).filter(isFinite);
+      const nearestExpiryMs = expiries.length ? Math.min(...expiries) : null;
+      const lowStock = (onHand === 0) || (onHand != null && reorder != null && onHand <= reorder);
+      return {
+        id: i.id, uid: i.uid, name: i.name || '', family: i.family || '',
+        stockOnHand: onHand, stockUnit: i.stockUnit || null,
+        reorderThreshold: reorder,
+        lotCount: lots.length,
+        lotBalance: lots.length ? +lotBalance.toFixed(4) : null,
+        nearestExpiry: nearestExpiryMs != null ? new Date(nearestExpiryMs).toISOString().slice(0, 10) : null,
+        daysToNearestExpiry: nearestExpiryMs != null ? Math.floor((nearestExpiryMs - nowMs) / 86400000) : null,
+        lowStock,
+      };
+    }).filter(r => {
+      if (args.low_stock_only && !r.lowStock) return false;
+      if (args.expiring_within_days != null) {
+        if (r.daysToNearestExpiry == null) return false;
+        if (r.daysToNearestExpiry > args.expiring_within_days) return false;
+      }
+      return true;
+    }).sort((a, b) => {
+      if (a.lowStock !== b.lowStock) return a.lowStock ? -1 : 1;
+      const av = a.stockOnHand == null ? Infinity : a.stockOnHand;
+      const bv = b.stockOnHand == null ? Infinity : b.stockOnHand;
+      return av - bv;
+    });
+    return {
+      totalMatching: rows.length,
+      returned: Math.min(rows.length, limit),
+      lowStockCount: rows.filter(r => r.lowStock).length,
+      inventory: rows.slice(0, limit),
+    };
+  },
+};
+
+export const tools = { list_ingredients, get_ingredient, find_by_smarts, list_lots, list_inventory };

package/tools/library.js

@@ -0,0 +1,360 @@
+// ============================================================
+// LIBRARY TOOLS — the shared reference entities that Panels,
+// Step Presets, formula steps, and test results point at:
+//   - Equipment       (list_equipment / get_equipment)
+//   - Test Methods    (list_test_methods / get_test_method)   [db.parameters]
+//   - Step Presets    (list_step_presets / get_step_preset)   [db.procedureTemplates]
+//   - Test Panels     (list_test_panels / get_test_panel)     [db.templates]
+//
+// All read-only. These expose the first-class Equipment registry,
+// the parameter/analyte library, and reusable procedure steps —
+// previously synced into the store but not queryable.
+// ============================================================
+
+import { getStore, resolveById } from '../data.js';
+
+const _norm = (s) => String(s == null ? '' : s).toLowerCase();
+const _clampLimit = (n) => Math.min(1000, Math.max(1, n || 100));
+
+// ── Equipment ───────────────────────────────────────────────
+function _trimEquipment(e) {
+  if (!e) return null;
+  return {
+    id: e.id, uid: e.uid, name: e.name || '',
+    category: e.category || '', status: e.status || '',
+    model: e.model || '', serial: e.serial || '',
+    manufacturer: e.manufacturer || '', location: e.location || '',
+    owner: e.owner || '', assetTag: e.assetTag || '',
+    ...(e.notes ? { notes: e.notes } : {}),
+  };
+}
+
+// Where an equipment record is referenced. Prefers the stable equipmentId,
+// falls back to a case-insensitive exact name match (legacy free-text entries).
+function _equipUsage(e, db) {
+  const id = e.id;
+  const nm = _norm(e.name);
+  const instMatch = (arr) => (arr || []).some(x =>
+    (x.equipmentId && x.equipmentId === id) || (!x.equipmentId && _norm(x.name) === nm));
+  const fieldMatch = (eqId, eqName) =>
+    (eqId && eqId === id) || (!eqId && nm && _norm(eqName) === nm);
+  // A step references equipment via the new equipmentList[] or the legacy flat field.
+  const stepMatch = (s) =>
+    (Array.isArray(s.equipmentList) && s.equipmentList.some(le => fieldMatch(le.equipmentId, le.name)))
+    || fieldMatch(s.equipmentId, s.equipment);
+
+  const panels   = (db.templates || []).filter(t => instMatch(t.instruments));
+  const presets  = (db.procedureTemplates || []).filter(t =>
+    instMatch(t.instruments) || (Array.isArray(t.equipmentList) && t.equipmentList.some(le => fieldMatch(le.equipmentId, le.name))) || fieldMatch(t.equipmentId, t.equipment));
+  const methods  = (db.parameters || []).filter(p => fieldMatch(p.equipmentId, p.equipment));
+  const formulas = (db.formulations || []).filter(f => (f.steps || []).some(stepMatch));
+  const batches  = (db.batches || []).filter(b =>
+    fieldMatch(b.equipmentUsedId, b.equipmentUsed) || (b.steps || []).some(stepMatch));
+  const name = (arr) => arr.map(x => x.uid || x.name).slice(0, 20);
+  return {
+    total: panels.length + presets.length + methods.length + formulas.length + batches.length,
+    panels: name(panels), stepPresets: name(presets), testMethods: name(methods),
+    formulas: name(formulas), batches: name(batches),
+  };
+}
+
+const list_equipment = {
+  definition: {
+    name: 'list_equipment',
+    description: 'List equipment / instruments in the FormLab Equipment registry (mixers, ovens, viscometers, balances…), optionally filtered by category, status, manufacturer, or name. Returns metadata; use get_equipment for one record plus where it is used.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        category: { type: 'string', description: 'Filter by category (e.g. "Viscometers & rheology", "Mixing & dispersion"). Case-insensitive substring.' },
+        status: { type: 'string', description: 'Filter by status (e.g. "In service", "Retired"). Case-insensitive substring.' },
+        manufacturer: { type: 'string', description: 'Filter by manufacturer. Case-insensitive substring.' },
+        name_contains: { type: 'string', description: 'Case-insensitive substring on equipment name / model / serial / asset tag.' },
+        limit: { type: 'number', description: 'Max rows (default 100, max 1000).' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const limit = _clampLimit(args.limit);
+    const filtered = (db.equipment || []).filter(e => {
+      if (!e || e._trashed) return false;
+      if (args.category && !_norm(e.category).includes(_norm(args.category))) return false;
+      if (args.status && !_norm(e.status).includes(_norm(args.status))) return false;
+      if (args.manufacturer && !_norm(e.manufacturer).includes(_norm(args.manufacturer))) return false;
+      if (args.name_contains) {
+        const q = _norm(args.name_contains);
+        const hay = [e.name, e.model, e.serial, e.assetTag].map(_norm).join(' ');
+        if (!hay.includes(q)) return false;
+      }
+      return true;
+    });
+    return {
+      totalMatching: filtered.length,
+      returned: Math.min(filtered.length, limit),
+      equipment: filtered.slice(0, limit).map(_trimEquipment),
+    };
+  },
+};
+
+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).',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string', description: 'Equipment UID or internal id.' } },
+      required: ['id'],
+    },
+  },
+  handler: async (args) => {
+    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) };
+  },
+};
+
+// ── Test Methods (parameters) ───────────────────────────────
+function _trimMethod(p, { full = false } = {}) {
+  if (!p) return null;
+  const base = {
+    id: p.id, uid: p.uid, name: p.name || '',
+    analyte: p.analyte || '',
+    category: p.category || '', type: p.type || 'scalar',
+    defaultUnit: p.defaultUnit || '', defaultMethod: p.defaultMethod || '',
+    spec: p.specRaw || '', decimals: p.decimals != null ? p.decimals : null,
+    retired: !!p.retired,
+  };
+  if (!full) return base;
+  return {
+    ...base,
+    acceptanceCriteria: p.acceptanceCriteria || null,
+    sopText: p.sopText || '', samplePrep: p.samplePrep || '',
+    equipment: p.equipment || '', equipmentId: p.equipmentId || '',
+    calcFormula: p.calcFormula || '', version: p.version != null ? p.version : null,
+    approvedBy: p.approvedBy || '', notes: p.notes || '',
+  };
+}
+
+const list_test_methods = {
+  definition: {
+    name: 'list_test_methods',
+    description: 'List Test Methods (the parameter library — the canonical definition of each measured reading: viscosity, gloss, pH…), optionally filtered by analyte (the property measured), category, name, or retired state. Methods of the same property at different conditions share an analyte.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        analyte: { type: 'string', description: 'Filter by analyte / property (e.g. "Viscosity"). Case-insensitive substring — finds every method measuring that property.' },
+        category: { type: 'string', description: 'Filter by category. Case-insensitive substring.' },
+        name_contains: { type: 'string', description: 'Case-insensitive substring on method name / default method-standard.' },
+        include_retired: { type: 'boolean', description: 'Include retired methods (default false).' },
+        limit: { type: 'number', description: 'Max rows (default 100, max 1000).' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const limit = _clampLimit(args.limit);
+    const filtered = (db.parameters || []).filter(p => {
+      if (!p || p._trashed) return false;
+      if (!args.include_retired && p.retired) return false;
+      if (args.analyte && !_norm(p.analyte).includes(_norm(args.analyte))) return false;
+      if (args.category && !_norm(p.category).includes(_norm(args.category))) return false;
+      if (args.name_contains) {
+        const q = _norm(args.name_contains);
+        if (!_norm(p.name).includes(q) && !_norm(p.defaultMethod).includes(q)) return false;
+      }
+      return true;
+    });
+    return {
+      totalMatching: filtered.length,
+      returned: Math.min(filtered.length, limit),
+      testMethods: filtered.slice(0, limit).map(p => _trimMethod(p)),
+    };
+  },
+};
+
+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, plus sibling methods that share its analyte (the same property measured at other conditions).',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string', description: 'Test Method UID or internal id.' } },
+      required: ['id'],
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const p = resolveById('parameters', args.id);
+    if (!p) return { error: `No test method found for "${args.id}".` };
+    const an = _norm(p.analyte);
+    const siblings = an
+      ? (db.parameters || []).filter(x => x.id !== p.id && _norm(x.analyte) === an).map(x => x.uid || x.name).slice(0, 20)
+      : [];
+    return { ...(_trimMethod(p, { full: true })), analyteSiblings: siblings };
+  },
+};
+
+// ── Step Presets (procedureTemplates) ───────────────────────
+function _trimPreset(t, { full = false } = {}) {
+  if (!t) return null;
+  const eqList = (Array.isArray(t.equipmentList) && t.equipmentList.length)
+    ? t.equipmentList.map(e => ({ name: e.name || '', equipmentId: e.equipmentId || '' })).filter(e => e.name)
+    : (t.equipment ? [{ name: t.equipment, equipmentId: t.equipmentId || '' }] : []);
+  const base = {
+    id: t.id, uid: t.uid, name: t.name || '',
+    industry: t.industry || '',
+    duration: t.duration != null ? t.duration : null,
+    temperature: t.temperature != null ? t.temperature : null,
+    rpm: t.rpm != null ? t.rpm : null,
+    equipment: eqList,
+  };
+  if (!full) return { ...base, description: (t.description || '').slice(0, 200) };
+  return { ...base, description: t.description || '', notes: t.notes || '' };
+}
+
+const list_step_presets = {
+  definition: {
+    name: 'list_step_presets',
+    description: 'List Step Presets (reusable manufacturing-step definitions — duration / temperature / RPM / equipment used when building a formula procedure), optionally filtered by industry or name. Equipment is the multi-value list of {name, equipmentId}.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        industry: { type: 'string', description: 'Filter by industry (e.g. "Paints & Coatings"). Case-insensitive substring.' },
+        name_contains: { type: 'string', description: 'Case-insensitive substring on preset name / description.' },
+        limit: { type: 'number', description: 'Max rows (default 100, max 1000).' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const limit = _clampLimit(args.limit);
+    const filtered = (db.procedureTemplates || []).filter(t => {
+      if (!t || t._trashed) return false;
+      if (args.industry && !_norm(t.industry).includes(_norm(args.industry))) return false;
+      if (args.name_contains) {
+        const q = _norm(args.name_contains);
+        if (!_norm(t.name).includes(q) && !_norm(t.description).includes(q)) return false;
+      }
+      return true;
+    });
+    return {
+      totalMatching: filtered.length,
+      returned: Math.min(filtered.length, limit),
+      stepPresets: filtered.slice(0, limit).map(t => _trimPreset(t)),
+    };
+  },
+};
+
+const get_step_preset = {
+  definition: {
+    name: 'get_step_preset',
+    description: 'Get one Step Preset by UID (e.g. PROC-001) or id — full description, notes, conditions, and equipment list (each {name, equipmentId}).',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string', description: 'Step Preset UID or internal id.' } },
+      required: ['id'],
+    },
+  },
+  handler: async (args) => {
+    const t = resolveById('procedureTemplates', args.id);
+    if (!t) return { error: `No step preset found for "${args.id}".` };
+    return _trimPreset(t, { full: true });
+  },
+};
+
+// ── Test Panels (templates) ─────────────────────────────────
+// A Test Panel is a reusable column-set: the ordered list of parameters
+// (test methods) measured together on a sample, plus the instruments used.
+// Each parameter row carries {parameter (name), parameterId, unit, spec…};
+// we resolve parameterId back to the Test Method UID for cross-reference.
+function _trimPanelParam(row, db) {
+  if (!row) return null;
+  const method = row.parameterId
+    ? (db.parameters || []).find(p => p && p.id === row.parameterId)
+    : null;
+  return {
+    parameter: row.parameter || row.name || '',
+    parameterId: row.parameterId || null,
+    methodUid: method ? (method.uid || null) : null,
+    unit: row.unit || (method && method.defaultUnit) || '',
+    ...(row.spec ? { spec: row.spec } : {}),
+    ...(row.method ? { method: row.method } : {}),
+  };
+}
+
+function _trimPanel(t, db, { full = false } = {}) {
+  if (!t) return null;
+  const params = Array.isArray(t.parameters) ? t.parameters : [];
+  const base = {
+    id: t.id, uid: t.uid, name: t.name || '',
+    industry: t.industry || '',
+    instruments: t.instruments || [],
+    parameterCount: params.length,
+  };
+  if (!full) return { ...base, description: (t.description || '').slice(0, 200) };
+  return {
+    ...base,
+    description: t.description || '',
+    notes: t.notes || '',
+    parameters: params.map(row => _trimPanelParam(row, db)),
+  };
+}
+
+const list_test_panels = {
+  definition: {
+    name: 'list_test_panels',
+    description: 'List Test Panels (reusable column-sets — the ordered group of parameters measured together on a sample, e.g. a "QC release" panel), optionally filtered by industry or name. Returns metadata + parameter count; use get_test_panel for the full parameter list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        industry: { type: 'string', description: 'Filter by industry. Case-insensitive substring.' },
+        name_contains: { type: 'string', description: 'Case-insensitive substring on panel name / description.' },
+        limit: { type: 'number', description: 'Max rows (default 100, max 1000).' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const limit = _clampLimit(args.limit);
+    const filtered = (db.templates || []).filter(t => {
+      if (!t || t._trashed) return false;
+      if (args.industry && !_norm(t.industry).includes(_norm(args.industry))) return false;
+      if (args.name_contains) {
+        const q = _norm(args.name_contains);
+        if (!_norm(t.name).includes(q) && !_norm(t.description).includes(q)) return false;
+      }
+      return true;
+    });
+    return {
+      totalMatching: filtered.length,
+      returned: Math.min(filtered.length, limit),
+      testPanels: filtered.slice(0, limit).map(t => _trimPanel(t, db)),
+    };
+  },
+};
+
+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.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string', description: 'Test Panel UID or internal id.' } },
+      required: ['id'],
+    },
+  },
+  handler: async (args) => {
+    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 });
+  },
+};
+
+export const tools = {
+  list_equipment, get_equipment,
+  list_test_methods, get_test_method,
+  list_step_presets, get_step_preset,
+  list_test_panels, get_test_panel,
+};

package/tools/notebook.js

@@ -0,0 +1,128 @@
+// ============================================================
+// NOTEBOOK TOOLS — the ELN thread. Each notebook entry is a dated,
+// authored note attached to some record (ingredient, formulation,
+// batch, sample, test result, project…) via {entityType, entityId}.
+//   - list_notebook_entries: filtered feed (by entity, author, text, date)
+//   - get_notebook_entry:    one entry, full body + attachment metadata
+//
+// The store syncs notebook_entries but nothing surfaced them, so the
+// lab's written record was invisible to the model. Read-only.
+// ============================================================
+
+import { getStore, resolveById } from '../data.js';
+
+const _norm = (s) => String(s == null ? '' : s).toLowerCase();
+const _clampLimit = (n) => Math.min(1000, Math.max(1, n || 100));
+
+// entityType → the db collection it points at, so we can resolve a
+// human label (uid / name) for the record an entry is attached to.
+const _ENTITY_COLLECTION = {
+  ingredient: 'ingredients', formulation: 'formulations', batch: 'batches',
+  sample: 'samples', test: 'testResults', testResult: 'testResults',
+  project: 'projects', equipment: 'equipment', parameter: 'parameters',
+};
+
+function _resolveEntity(entityType, entityId, db) {
+  const coll = _ENTITY_COLLECTION[entityType];
+  if (!coll || !entityId) return null;
+  const rec = (db[coll] || []).find(x => x && (x.id === entityId || x.uid === entityId));
+  if (!rec) return null;
+  return { uid: rec.uid || null, name: rec.name || rec.title || '' };
+}
+
+function _entryTs(e) { return e.ts || e.createdAt || e.updatedAt || null; }
+
+function _trimEntry(e, db, { full = false } = {}) {
+  if (!e) return null;
+  const linked = _resolveEntity(e.entityType, e.entityId, db);
+  const atts = Array.isArray(e.attachments) ? e.attachments : [];
+  const base = {
+    id: e.id,
+    entityType: e.entityType || '',
+    entityId: e.entityId || '',
+    entityUid: linked ? linked.uid : null,
+    entityName: linked ? linked.name : '',
+    ts: _entryTs(e),
+    updatedAt: e.updatedAt || null,
+    author: e.author || '',
+    attachmentCount: atts.length,
+  };
+  if (!full) return { ...base, body: (e.body || '').slice(0, 240) };
+  return {
+    ...base,
+    body: e.body || '',
+    attachments: atts.map(a => ({ id: a.id || null, filename: a.filename || '', type: a.type || '' })),
+  };
+}
+
+const list_notebook_entries = {
+  definition: {
+    name: 'list_notebook_entries',
+    description: 'List ELN notebook entries — dated, authored notes attached to records — optionally filtered by the record they hang off (entity_type + entity_id), author, text, or date range. Newest first. Use get_notebook_entry for the full body + attachments.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        entity_type: { type: 'string', description: 'Kind of record the note is attached to: ingredient, formulation, batch, sample, test, project, equipment, parameter.' },
+        entity_id: { type: 'string', description: 'The specific record the note is attached to (internal id or UID, e.g. FORM-001). Resolved to its id automatically.' },
+        author: { type: 'string', description: 'Filter by author. Case-insensitive substring.' },
+        text_contains: { type: 'string', description: 'Case-insensitive substring on the note body.' },
+        since: { type: 'string', description: 'ISO date/time — only entries at or after this timestamp.' },
+        until: { type: 'string', description: 'ISO date/time — only entries at or before this timestamp.' },
+        limit: { type: 'number', description: 'Max rows (default 100, max 1000).' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const limit = _clampLimit(args.limit);
+    // Resolve a UID-or-id entity reference down to its internal id so the
+    // filter matches regardless of which form the caller passed.
+    let wantEntityId = args.entity_id || null;
+    if (wantEntityId) {
+      const coll = _ENTITY_COLLECTION[args.entity_type] || null;
+      const rec = coll ? (db[coll] || []).find(x => x && (x.id === wantEntityId || x.uid === wantEntityId)) : null;
+      if (rec) wantEntityId = rec.id;
+    }
+    const sinceMs = args.since ? Date.parse(args.since) : null;
+    const untilMs = args.until ? Date.parse(args.until) : null;
+    const filtered = (db.notebookEntries || []).filter(e => {
+      if (!e || e._trashed) return false;
+      if (args.entity_type && _norm(e.entityType) !== _norm(args.entity_type)) return false;
+      if (wantEntityId && e.entityId !== wantEntityId) return false;
+      if (args.author && !_norm(e.author).includes(_norm(args.author))) return false;
+      if (args.text_contains && !_norm(e.body).includes(_norm(args.text_contains))) return false;
+      if (sinceMs != null || untilMs != null) {
+        const t = Date.parse(_entryTs(e));
+        if (!isFinite(t)) return false;
+        if (sinceMs != null && t < sinceMs) return false;
+        if (untilMs != null && t > untilMs) return false;
+      }
+      return true;
+    }).sort((a, b) => Date.parse(_entryTs(b) || 0) - Date.parse(_entryTs(a) || 0));
+    return {
+      totalMatching: filtered.length,
+      returned: Math.min(filtered.length, limit),
+      entries: filtered.slice(0, limit).map(e => _trimEntry(e, db)),
+    };
+  },
+};
+
+const get_notebook_entry = {
+  definition: {
+    name: 'get_notebook_entry',
+    description: 'Get one ELN notebook entry by id — full note body, author, timestamp, the record it is attached to (resolved to uid/name), and attachment metadata (filename / type). Attachment binaries are not returned.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string', description: 'Internal id of the notebook entry.' } },
+      required: ['id'],
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const e = (db.notebookEntries || []).find(x => x && x.id === args.id);
+    if (!e) return { error: `No notebook entry found for id "${args.id}".` };
+    return _trimEntry(e, db, { full: true });
+  },
+};
+
+export const tools = { list_notebook_entries, get_notebook_entry };

package/tools/projects.js

@@ -0,0 +1,90 @@
+// ============================================================
+// PROJECT TOOLS
+//   - list_projects: the project register (name / status / description)
+//   - get_project:   one project + the formulations filed under it
+//
+// Projects are the top-level organizing bucket: formulations point at a
+// project via `projectId`. Previously the store synced projects but they
+// were only usable as a *filter* on list_formulations — never listable or
+// openable on their own. These two tools close that gap.
+// ============================================================
+
+import { getStore, resolveById } from '../data.js';
+
+const _norm = (s) => String(s == null ? '' : s).toLowerCase();
+const _clampLimit = (n) => Math.min(1000, Math.max(1, n || 100));
+
+function _trimProject(p, formulationCount) {
+  if (!p) return null;
+  return {
+    id: p.id, uid: p.uid, name: p.name || '',
+    status: p.status || '',
+    description: (p.description || '').slice(0, 200),
+    createdAt: p.createdAt || null,
+    updatedAt: p.updatedAt || null,
+    formulationCount,
+  };
+}
+
+// Formulations filed under a project (top-level projectId link).
+function _projectFormulas(projectId, db) {
+  return (db.formulations || []).filter(f => f && !f._trashed && f.projectId === projectId);
+}
+
+const list_projects = {
+  definition: {
+    name: 'list_projects',
+    description: 'List projects — the top-level buckets that formulations are filed under — optionally filtered by status or name. Each row includes how many formulations belong to the project. Use get_project for one project plus its formulation list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: { type: 'string', description: 'Filter by status (e.g. "Active", "On hold"). Case-insensitive substring.' },
+        name_contains: { type: 'string', description: 'Case-insensitive substring on project name / description.' },
+        limit: { type: 'number', description: 'Max rows (default 100, max 1000).' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const limit = _clampLimit(args.limit);
+    const filtered = (db.projects || []).filter(p => {
+      if (!p || p._trashed) return false;
+      if (args.status && !_norm(p.status).includes(_norm(args.status))) return false;
+      if (args.name_contains) {
+        const q = _norm(args.name_contains);
+        if (!_norm(p.name).includes(q) && !_norm(p.description).includes(q)) return false;
+      }
+      return true;
+    });
+    return {
+      totalMatching: filtered.length,
+      returned: Math.min(filtered.length, limit),
+      projects: filtered.slice(0, limit).map(p => _trimProject(p, _projectFormulas(p.id, db).length)),
+    };
+  },
+};
+
+const get_project = {
+  definition: {
+    name: 'get_project',
+    description: 'Get one project by UID (e.g. PROJ-001) or id — full description plus the list of formulations filed under it (id / uid / name / status).',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string', description: 'Project UID or internal id.' } },
+      required: ['id'],
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const p = resolveById('projects', args.id);
+    if (!p) return { error: `No project found for "${args.id}".` };
+    const formulas = _projectFormulas(p.id, db);
+    return {
+      ..._trimProject(p, formulas.length),
+      description: p.description || '',
+      formulations: formulas.slice(0, 200).map(f => ({ id: f.id, uid: f.uid, name: f.name || '', status: f.status || '' })),
+    };
+  },
+};
+
+export const tools = { list_projects, get_project };