formlab-mcp 0.1.0

package/tools/analytics.js

@@ -0,0 +1,426 @@
+// ============================================================
+// ANALYTICS TOOLS — the headline value of the MCP for AI use:
+//   - list_test_results
+//   - get_test_result
+//   - get_doe_matrix         (the same shape the DOE Matrix UI produces)
+//   - find_failures          (Pareto-style: which params fail most)
+//   - get_coverage_matrix    (which items × parameters have been tested)
+// ============================================================
+
+import { getStore, resolveById, flattenComposition } from '../data.js';
+
+function _trimTest(t, samplesById) {
+  if (!t) return null;
+  const s = t.sampleId ? samplesById.get(t.sampleId) : null;
+  return {
+    id: t.id,
+    uid: t.uid,
+    reportName: t.reportName || '',
+    sample: s ? { id: s.id, uid: s.uid } : null,
+    testDate: t.testDate || '',
+    performedBy: t.performedBy || '',
+    lab: t.lab || '',
+    measurementCount: (t.measurements || []).length,
+    parameters: [...new Set((t.measurements || []).map(m => m.parameter).filter(Boolean))],
+  };
+}
+
+function _trimMeasurement(m) {
+  return {
+    parameter: m.parameter || '',
+    value: m.value ?? null,
+    unit: m.unit || '',
+    type: m.type || 'scalar',
+    pointCount: Array.isArray(m.points) ? m.points.length : 0,
+    binCount: Array.isArray(m.bins) ? m.bins.length : 0,
+    acceptanceCriteria: m.acceptanceCriteria || null,
+  };
+}
+
+const list_test_results = {
+  definition: {
+    name: 'list_test_results',
+    description: 'List test result reports, optionally filtered by sample, parameter, date range, or lab. Returns metadata + parameters tested. Use get_test_result for full measurement values.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sample_id: { type: 'string', description: 'Filter to results for this sample (id or UID).' },
+        parameter: { type: 'string', description: 'Filter to results that include this parameter (case-insensitive substring).' },
+        since_date: { type: 'string', description: 'ISO date — only reports on/after this date.' },
+        until_date: { type: 'string', description: 'ISO date — only reports on/before this date.' },
+        lab: { type: 'string', description: 'Filter by lab name (case-insensitive substring).' },
+        limit: { type: 'number', description: 'Max rows (default 100, max 1000).' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db, indexes } = getStore();
+    const limit = Math.min(1000, Math.max(1, args.limit || 100));
+    const norm = (s) => String(s || '').toLowerCase();
+    let sampleId = null;
+    if (args.sample_id) {
+      const s = resolveById('samples', args.sample_id);
+      if (!s) return { error: `No sample matched "${args.sample_id}".` };
+      sampleId = s.id;
+    }
+    const filtered = (db.testResults || []).filter(t => {
+      if (!t || t._trashed) return false;
+      if (sampleId && t.sampleId !== sampleId) return false;
+      if (args.since_date && (t.testDate || '') < args.since_date) return false;
+      if (args.until_date && (t.testDate || '') > args.until_date) return false;
+      if (args.lab && !norm(t.lab).includes(norm(args.lab))) return false;
+      if (args.parameter) {
+        const found = (t.measurements || []).some(m => norm(m.parameter).includes(norm(args.parameter)));
+        if (!found) return false;
+      }
+      return true;
+    });
+    return {
+      totalMatching: filtered.length,
+      returned: Math.min(filtered.length, limit),
+      testResults: filtered.slice(0, limit).map(t => _trimTest(t, indexes.samplesById)),
+    };
+  },
+};
+
+const get_test_result = {
+  definition: {
+    name: 'get_test_result',
+    description: 'Get full details for a single test result report including every measurement\'s value, unit, type, and acceptance criteria. Accepts internal id or UID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Internal id or UID of the test result.' },
+      },
+      required: ['id'],
+    },
+  },
+  handler: async (args) => {
+    const { indexes } = getStore();
+    const t = resolveById('testResults', args.id);
+    if (!t) return { error: `No test result found for id "${args.id}".` };
+    return {
+      ..._trimTest(t, indexes.samplesById),
+      notes: t.notes || '',
+      measurements: (t.measurements || []).map(_trimMeasurement),
+    };
+  },
+};
+
+const get_doe_matrix = {
+  definition: {
+    name: 'get_doe_matrix',
+    description: 'Build a Design-of-Experiments style pivot matrix: rows = formulations (or samples / batches / tests), columns = composition wt-% per ingredient + aggregated test-parameter values. Same shape as the FormLab DOE Matrix view. Returns CSV when format=csv (default) for compact LLM consumption, or structured JSON when format=json.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        grain: { type: 'string', enum: ['formulation', 'sample', 'batch', 'test'], description: 'Row grain. Default "formulation".' },
+        format: { type: 'string', enum: ['csv', 'json'], description: 'Output format. CSV is recommended for LLM consumption (compact). Default "csv".' },
+        formulation_ids: { type: 'array', items: { type: 'string' }, description: 'Restrict to specific formulation ids/UIDs.' },
+        parameter_filter: { type: 'string', description: 'Case-insensitive substring; restrict parameter columns.' },
+        limit_rows: { type: 'number', description: 'Max rows (default 100, max 500).' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db, indexes } = getStore();
+    const grain = args.grain || 'formulation';
+    const fmt = args.format || 'csv';
+    const limit = Math.min(500, Math.max(1, args.limit_rows || 100));
+    const norm = (s) => String(s || '').toLowerCase();
+
+    // 1) Resolve formula filter
+    let allowedFormulaIds = null;
+    if (Array.isArray(args.formulation_ids) && args.formulation_ids.length) {
+      const ids = args.formulation_ids.map(i => resolveById('formulations', i)?.id).filter(Boolean);
+      if (!ids.length) return { error: 'None of the provided formulation_ids matched a formula.' };
+      allowedFormulaIds = new Set(ids);
+    }
+
+    // 2) Build rows + per-row composition map + per-row measurements
+    const rows = [];
+    const addRow = (label, formulationId, measurements, batchActualComp) => {
+      let composition = null;
+      // For the composition, prefer batch.actualComposition if present
+      // (matches the "Use measured" semantics in the FormLab UI when the
+      // grain is batch/sample/test); else flatten the proposal formula.
+      const f = formulationId ? indexes.formulationsById.get(formulationId) : null;
+      if (batchActualComp && Array.isArray(batchActualComp) && batchActualComp.length) {
+        composition = new Map();
+        batchActualComp.forEach(c => {
+          if (c && c.ingredientId) {
+            const amt = parseFloat(c.amount);
+            if (isFinite(amt)) composition.set(c.ingredientId, amt);
+          }
+        });
+      } else if (f) {
+        const flat = flattenComposition(f);
+        composition = new Map(flat.rows.map(r => [r.ingredientId, +(r.weightFraction * 100).toFixed(4)]));
+      } else {
+        composition = new Map();
+      }
+      rows.push({ label, composition, measurements: measurements || [] });
+    };
+
+    if (grain === 'formulation') {
+      (db.formulations || []).forEach(f => {
+        if (!f || f._trashed) return;
+        if (allowedFormulaIds && !allowedFormulaIds.has(f.id)) return;
+        const samples = (db.samples || []).filter(s => s.formulationId === f.id);
+        const sampleIds = new Set(samples.map(s => s.id));
+        const measurements = (db.testResults || [])
+          .filter(t => sampleIds.has(t.sampleId))
+          .flatMap(t => t.measurements || []);
+        addRow(f.name || f.uid || f.id, f.id, measurements);
+      });
+    } else if (grain === 'batch') {
+      (db.batches || []).forEach(b => {
+        if (!b || b._trashed) return;
+        if (allowedFormulaIds && !allowedFormulaIds.has(b.formulationId)) return;
+        const samples = (db.samples || []).filter(s => s.batchId === b.id);
+        const sampleIds = new Set(samples.map(s => s.id));
+        const measurements = (db.testResults || [])
+          .filter(t => sampleIds.has(t.sampleId))
+          .flatMap(t => t.measurements || []);
+        addRow(b.uid || b.id, b.formulationId, measurements, b.actualComposition);
+      });
+    } else if (grain === 'sample') {
+      (db.samples || []).forEach(s => {
+        if (!s || s._trashed) return;
+        if (allowedFormulaIds && !allowedFormulaIds.has(s.formulationId)) return;
+        const measurements = (db.testResults || [])
+          .filter(t => t.sampleId === s.id)
+          .flatMap(t => t.measurements || []);
+        const batch = s.batchId ? indexes.batchesById.get(s.batchId) : null;
+        addRow(s.uid || s.id, s.formulationId, measurements, batch?.actualComposition);
+      });
+    } else if (grain === 'test') {
+      (db.testResults || []).forEach(t => {
+        if (!t || t._trashed) return;
+        const samp = indexes.samplesById.get(t.sampleId);
+        if (allowedFormulaIds && !allowedFormulaIds.has(samp?.formulationId)) return;
+        const batch = samp?.batchId ? indexes.batchesById.get(samp.batchId) : null;
+        addRow(t.uid || t.id, samp?.formulationId, t.measurements || [], batch?.actualComposition);
+      });
+    }
+
+    // 3) Build column sets
+    const ingredientIds = new Set();
+    const parameters = new Set();
+    rows.forEach(r => {
+      r.composition.forEach((_, k) => ingredientIds.add(k));
+      r.measurements.forEach(m => {
+        if (!m.parameter) return;
+        if (args.parameter_filter && !norm(m.parameter).includes(norm(args.parameter_filter))) return;
+        parameters.add(m.parameter);
+      });
+    });
+    const ingCols = [...ingredientIds].map(id => {
+      const ing = indexes.ingredientsById.get(id);
+      return { id, label: (ing?.name || id) + ' (%)' };
+    });
+    const paramCols = [...parameters].map(p => ({ id: p, label: p }));
+
+    // 4) Aggregate measurements per param per row (mean of numeric scalar values)
+    const cellParamValue = (r, param) => {
+      const ms = r.measurements.filter(m => m.parameter === param);
+      if (!ms.length) return null;
+      const nums = ms.map(m => parseFloat(m.value)).filter(v => isFinite(v));
+      if (!nums.length) return ms[0].value ?? null;
+      const mean = nums.reduce((s, v) => s + v, 0) / nums.length;
+      return +mean.toFixed(4);
+    };
+
+    const limitedRows = rows.slice(0, limit);
+
+    if (fmt === 'json') {
+      return {
+        grain,
+        rowCount: rows.length,
+        rowsReturned: limitedRows.length,
+        ingredientColumnCount: ingCols.length,
+        parameterColumnCount: paramCols.length,
+        columns: { label: 'Row', ingredients: ingCols.map(c => c.label), parameters: paramCols.map(c => c.label) },
+        rows: limitedRows.map(r => ({
+          label: r.label,
+          ingredientPct: Object.fromEntries(ingCols.map(c => [c.label, r.composition.get(c.id) ?? null])),
+          parameterMean: Object.fromEntries(paramCols.map(c => [c.label, cellParamValue(r, c.id)])),
+        })),
+      };
+    }
+
+    // CSV format (default — compact, easy to paste into a spreadsheet)
+    const escCSV = (v) => {
+      if (v == null) return '';
+      const s = String(v);
+      return /[",\n\r]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+    };
+    const headerCells = ['Row', ...ingCols.map(c => c.label), ...paramCols.map(c => c.label)];
+    const lines = [headerCells.map(escCSV).join(',')];
+    limitedRows.forEach(r => {
+      const cells = [
+        r.label,
+        ...ingCols.map(c => r.composition.get(c.id) ?? ''),
+        ...paramCols.map(c => cellParamValue(r, c.id) ?? ''),
+      ];
+      lines.push(cells.map(escCSV).join(','));
+    });
+    const summary = `# DOE Matrix · grain=${grain} · ${limitedRows.length}/${rows.length} rows · ${ingCols.length} ingredient cols · ${paramCols.length} parameter cols`;
+    return [summary, ...lines].join('\n');
+  },
+};
+
+const find_failures = {
+  definition: {
+    name: 'find_failures',
+    description: 'Pareto-style failure analysis: which test parameters fail their acceptance criteria most often, and on which samples / formulations. Returns ranked list of (parameter, failureCount, failureRate, exampleFailures).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        parameter: { type: 'string', description: 'Restrict to a single parameter (case-insensitive substring).' },
+        since_date: { type: 'string', description: 'ISO date — only failures since this date.' },
+        limit_params: { type: 'number', description: 'Max parameters in the Pareto. Default 10.' },
+        limit_examples_per_param: { type: 'number', description: 'Max example failures per parameter row. Default 5.' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db, indexes } = getStore();
+    const limitParams = Math.min(50, Math.max(1, args.limit_params || 10));
+    const limitExamples = Math.min(20, Math.max(1, args.limit_examples_per_param || 5));
+    const norm = (s) => String(s || '').toLowerCase();
+
+    // Per-parameter aggregator
+    const byParam = new Map();
+    (db.testResults || []).forEach(t => {
+      if (!t || t._trashed) return;
+      if (args.since_date && (t.testDate || '') < args.since_date) return;
+      (t.measurements || []).forEach(m => {
+        if (!m || !m.parameter) return;
+        if (args.parameter && !norm(m.parameter).includes(norm(args.parameter))) return;
+        if (!byParam.has(m.parameter)) {
+          byParam.set(m.parameter, { total: 0, failures: 0, examples: [] });
+        }
+        const agg = byParam.get(m.parameter);
+        agg.total += 1;
+        const pf = _evalPassFail(m);
+        if (pf === 'fail') {
+          agg.failures += 1;
+          if (agg.examples.length < limitExamples) {
+            const samp = indexes.samplesById.get(t.sampleId);
+            const f = samp?.formulationId ? indexes.formulationsById.get(samp.formulationId) : null;
+            agg.examples.push({
+              testId: t.uid || t.id,
+              testDate: t.testDate || '',
+              sample: samp ? (samp.uid || samp.id) : '',
+              formulation: f ? (f.name || f.uid) : '',
+              value: m.value,
+              unit: m.unit,
+              spec: m.acceptanceCriteria || null,
+            });
+          }
+        }
+      });
+    });
+
+    const ranked = [...byParam.entries()]
+      .map(([param, agg]) => ({
+        parameter: param,
+        totalMeasured: agg.total,
+        failureCount: agg.failures,
+        failureRate: agg.total ? +(agg.failures / agg.total * 100).toFixed(2) : 0,
+        examples: agg.examples,
+      }))
+      .filter(r => r.failureCount > 0)
+      .sort((a, b) => b.failureCount - a.failureCount)
+      .slice(0, limitParams);
+
+    return {
+      totalParamsConsidered: byParam.size,
+      paramsWithFailures: ranked.length,
+      ranked,
+    };
+  },
+};
+
+// Minimal pass/fail evaluator — mirrors FormLab's _evalPassFail logic
+// for scalar numeric measurements with min/max/target acceptance.
+function _evalPassFail(m) {
+  if (!m || m.value == null || m.value === '') return 'untested';
+  const spec = m.acceptanceCriteria;
+  if (!spec) return 'no-criteria';
+  const v = parseFloat(m.value);
+  if (!isFinite(v)) {
+    // Non-numeric required value
+    if (spec.requiredValue != null) {
+      return String(m.value).trim() === String(spec.requiredValue).trim() ? 'pass' : 'fail';
+    }
+    return 'no-criteria';
+  }
+  if (spec.target != null) return Math.abs(v - parseFloat(spec.target)) <= (spec.tolerance ?? 0) ? 'pass' : 'fail';
+  if (spec.min != null && v < parseFloat(spec.min)) return 'fail';
+  if (spec.max != null && v > parseFloat(spec.max)) return 'fail';
+  return 'pass';
+}
+
+const get_coverage_matrix = {
+  definition: {
+    name: 'get_coverage_matrix',
+    description: 'Coverage map: which formulations have been tested on which parameters. Returns counts per (formulation × parameter) cell so the LLM can answer "what\'s untested" or "what\'s been measured many times" questions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        formulation_ids: { type: 'array', items: { type: 'string' }, description: 'Restrict to specific formulation ids/UIDs.' },
+        parameter_filter: { type: 'string', description: 'Case-insensitive substring; restrict parameter columns.' },
+        format: { type: 'string', enum: ['csv', 'json'], description: 'Output format. Default csv.' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db, indexes } = getStore();
+    const norm = (s) => String(s || '').toLowerCase();
+    const fmt = args.format || 'csv';
+    let allowed = null;
+    if (Array.isArray(args.formulation_ids) && args.formulation_ids.length) {
+      const ids = args.formulation_ids.map(i => resolveById('formulations', i)?.id).filter(Boolean);
+      allowed = new Set(ids);
+    }
+    const counts = new Map(); // formId -> Map(param -> count)
+    (db.testResults || []).forEach(t => {
+      if (!t || t._trashed) return;
+      const samp = indexes.samplesById.get(t.sampleId);
+      const formId = samp?.formulationId;
+      if (!formId) return;
+      if (allowed && !allowed.has(formId)) return;
+      if (!counts.has(formId)) counts.set(formId, new Map());
+      const inner = counts.get(formId);
+      (t.measurements || []).forEach(m => {
+        if (!m || !m.parameter) return;
+        if (args.parameter_filter && !norm(m.parameter).includes(norm(args.parameter_filter))) return;
+        inner.set(m.parameter, (inner.get(m.parameter) || 0) + 1);
+      });
+    });
+    const allParams = new Set();
+    counts.forEach(inner => inner.forEach((_, p) => allParams.add(p)));
+    const paramCols = [...allParams].sort();
+    const formRows = [...counts.entries()].map(([fid, inner]) => {
+      const f = indexes.formulationsById.get(fid);
+      return { formulation: f?.name || f?.uid || fid, formulationId: fid, ...Object.fromEntries(paramCols.map(p => [p, inner.get(p) || 0])) };
+    });
+    if (fmt === 'json') {
+      return { formulationCount: formRows.length, parameterCount: paramCols.length, parameters: paramCols, rows: formRows };
+    }
+    const esc = (v) => /[",\n\r]/.test(String(v || '')) ? '"' + String(v).replace(/"/g, '""') + '"' : String(v ?? '');
+    const lines = [['Formulation', ...paramCols].map(esc).join(',')];
+    formRows.forEach(r => lines.push([r.formulation, ...paramCols.map(p => r[p])].map(esc).join(',')));
+    return `# Coverage Matrix · ${formRows.length} formulations × ${paramCols.length} parameters\n` + lines.join('\n');
+  },
+};
+
+export const tools = {
+  list_test_results,
+  get_test_result,
+  get_doe_matrix,
+  find_failures,
+  get_coverage_matrix,
+};

package/tools/formulations.js

@@ -0,0 +1,214 @@
+// ============================================================
+// FORMULATION TOOLS
+//   - list_formulations: filtered list
+//   - get_formulation: full record with composition + sub-formula flatten
+//   - find_similar_formulations: ingredient-pattern search
+//   - compare_formulations: pairwise composition diff
+// ============================================================
+
+import { getStore, resolveById, flattenComposition } from '../data.js';
+
+// Strip db-internal noise (createdAt, updatedAt) for cleaner LLM output
+// while keeping the human-facing fields the user cares about.
+function _trimFormulation(f) {
+  if (!f) return null;
+  return {
+    id: f.id,
+    uid: f.uid,
+    name: f.name,
+    description: f.description || '',
+    status: f.status || 'Draft',
+    family: f.family || '',
+    application: f.application || '',
+    owner: f.owner || '',
+    regulatoryCategory: f.regulatoryCategory || '',
+    tags: f.tags || [],
+    projectId: f.projectId || null,
+    compositionRowCount: (f.composition || []).length,
+    hasSubFormulas: (f.composition || []).some(c => c && c.formulationId),
+    updatedAt: f.updatedAt || null,
+  };
+}
+
+const list_formulations = {
+  definition: {
+    name: 'list_formulations',
+    description: 'List formulations (recipes) in the FormLab database, optionally filtered by status, project, family, tag, or name pattern. Returns one row per formula with key metadata. Use get_formulation for the full composition.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: { type: 'string', description: 'Filter by status (e.g. "Approved", "In Development"). Case-insensitive substring match.' },
+        project: { type: 'string', description: 'Filter by project name or id.' },
+        family: { type: 'string', description: 'Filter by formula family (e.g. "Acrylic Coating", "Skin Serum"). Case-insensitive substring.' },
+        tag: { type: 'string', description: 'Filter to formulas containing this tag.' },
+        name_contains: { type: 'string', description: 'Case-insensitive substring match on formula name.' },
+        limit: { type: 'number', description: 'Max rows to return (default 50, max 500).' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db, indexes } = getStore();
+    const limit = Math.min(500, Math.max(1, args.limit || 50));
+    const all = (db.formulations || []).filter(f => f && !f._trashed);
+    const norm = (s) => String(s || '').toLowerCase();
+    const filtered = all.filter(f => {
+      if (args.status && !norm(f.status).includes(norm(args.status))) return false;
+      if (args.project) {
+        const p = indexes.projectsById.get(args.project)
+          || (db.projects || []).find(x => norm(x.name) === norm(args.project));
+        if (!p || f.projectId !== p.id) return false;
+      }
+      if (args.family && !norm(f.family).includes(norm(args.family))) return false;
+      if (args.tag && !(f.tags || []).some(t => norm(t) === norm(args.tag))) return false;
+      if (args.name_contains && !norm(f.name).includes(norm(args.name_contains))) return false;
+      return true;
+    });
+    return {
+      totalMatching: filtered.length,
+      returned: Math.min(filtered.length, limit),
+      formulations: filtered.slice(0, limit).map(_trimFormulation),
+    };
+  },
+};
+
+const get_formulation = {
+  definition: {
+    name: 'get_formulation',
+    description: 'Get full details for a single formulation including its composition (raw rows AND flattened wt-% leaves with sub-formulas expanded), step procedure, and recent batches. Accepts either internal id or UID (e.g. FORM-001).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Internal id or UID (FORM-001) of the formulation.' },
+      },
+      required: ['id'],
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const f = resolveById('formulations', args.id);
+    if (!f) return { error: `No formulation found for id "${args.id}".` };
+    const flat = flattenComposition(f);
+    const flatRows = flat.rows.map(r => ({
+      ingredientId: r.ingredientId,
+      ingredient: r.ingredientName,
+      role: r.role || '',
+      wtPct: +(r.weightFraction * 100).toFixed(4),
+    })).sort((a, b) => b.wtPct - a.wtPct);
+    const batches = (db.batches || []).filter(b => b.formulationId === f.id);
+    const samples = (db.samples || []).filter(s => s.formulationId === f.id);
+    return {
+      ..._trimFormulation(f),
+      compositionRaw: (f.composition || []).map(c => ({
+        ingredientId: c.ingredientId || null,
+        subFormulationId: c.formulationId || null,
+        amount: c.amount,
+        unit: c.unit,
+        role: c.role || '',
+      })),
+      compositionFlattenedWtPct: flatRows,
+      stepCount: (f.steps || []).length,
+      batchCount: batches.length,
+      sampleCount: samples.length,
+    };
+  },
+};
+
+const find_similar_formulations = {
+  definition: {
+    name: 'find_similar_formulations',
+    description: 'Find formulations whose flattened composition contains a given ingredient (by name or id) above a threshold wt-%. Useful for "what other formulas use silicone oil at ≥5%" queries. Returns ranked by wt-% descending.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ingredient: { type: 'string', description: 'Ingredient name (case-insensitive substring) or id/UID.' },
+        min_wt_pct: { type: 'number', description: 'Minimum wt-% (0-100). Default 0.1.' },
+        limit: { type: 'number', description: 'Max formulas to return. Default 20.' },
+      },
+      required: ['ingredient'],
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const limit = Math.min(200, Math.max(1, args.limit || 20));
+    const minPct = args.min_wt_pct ?? 0.1;
+    const norm = (s) => String(s || '').toLowerCase();
+    const q = norm(args.ingredient);
+    // Resolve target ingredient(s) — substring match on name, plus exact match on id/UID
+    const targets = (db.ingredients || []).filter(i =>
+      i && (i.id === args.ingredient || i.uid === args.ingredient || norm(i.name).includes(q))
+    );
+    if (!targets.length) return { matches: [], note: `No ingredient matched "${args.ingredient}".` };
+    const targetIds = new Set(targets.map(i => i.id));
+    const hits = [];
+    (db.formulations || []).forEach(f => {
+      if (!f || f._trashed) return;
+      const flat = flattenComposition(f);
+      flat.rows.forEach(r => {
+        if (!targetIds.has(r.ingredientId)) return;
+        const pct = r.weightFraction * 100;
+        if (pct < minPct) return;
+        hits.push({
+          formulationId: f.id,
+          formulationUid: f.uid,
+          formulationName: f.name,
+          ingredient: r.ingredientName,
+          wtPct: +pct.toFixed(4),
+        });
+      });
+    });
+    hits.sort((a, b) => b.wtPct - a.wtPct);
+    return {
+      targets: targets.map(t => ({ id: t.id, uid: t.uid, name: t.name })),
+      matchCount: hits.length,
+      matches: hits.slice(0, limit),
+    };
+  },
+};
+
+const compare_formulations = {
+  definition: {
+    name: 'compare_formulations',
+    description: 'Compare two or more formulations side-by-side on the same set of leaf ingredients (flattened wt-%). Returns one row per ingredient with each formula\'s wt-% in its own column. Useful for "what\'s different between Formula A and Formula B" questions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ids: { type: 'array', items: { type: 'string' }, description: 'Formula ids or UIDs (e.g. ["FORM-001", "FORM-005"]).' },
+      },
+      required: ['ids'],
+    },
+  },
+  handler: async (args) => {
+    if (!Array.isArray(args.ids) || args.ids.length < 2) return { error: 'Pass at least 2 formula ids.' };
+    const formulas = args.ids.map(id => resolveById('formulations', id)).filter(Boolean);
+    if (formulas.length < 2) return { error: 'Fewer than 2 of the supplied ids resolved to existing formulas.' };
+    const colByForm = formulas.map(f => {
+      const flat = flattenComposition(f);
+      const m = new Map();
+      flat.rows.forEach(r => m.set(r.ingredientId, { name: r.ingredientName, pct: +(r.weightFraction * 100).toFixed(4) }));
+      return { formula: f, map: m };
+    });
+    const allIngIds = new Set();
+    colByForm.forEach(c => c.map.forEach((_, k) => allIngIds.add(k)));
+    const rows = [...allIngIds].map(ingId => {
+      const ref = colByForm.find(c => c.map.get(ingId))?.map.get(ingId);
+      const out = { ingredientId: ingId, ingredient: ref?.name || ingId };
+      colByForm.forEach(c => { out[c.formula.uid || c.formula.id] = c.map.get(ingId)?.pct ?? null; });
+      // Add deltaMax: max - min wt-% across formulas, sortable so caller can find biggest differences fast
+      const vals = colByForm.map(c => c.map.get(ingId)?.pct ?? 0);
+      out.deltaMax = +(Math.max(...vals) - Math.min(...vals)).toFixed(4);
+      return out;
+    }).sort((a, b) => b.deltaMax - a.deltaMax);
+    return {
+      formulas: formulas.map(f => ({ id: f.id, uid: f.uid, name: f.name })),
+      ingredientCount: rows.length,
+      rows,
+    };
+  },
+};
+
+export const tools = {
+  list_formulations,
+  get_formulation,
+  find_similar_formulations,
+  compare_formulations,
+};