formlab-mcp 0.6.3 → 0.6.5

package/README.md

@@ -19,6 +19,7 @@ Ask Claude (or another MCP client) things like:
 - _"What parameters fail most often in Q2 testing?"_
 - _"Show me the DOE matrix at sample grain for all 'Anti-aging serum' family formulas."_
 - _"What's untested? Which of my approved formulas have no measurements yet?"_
+- _"Map the design space of my WallPaint project — which ingredients vary, and what combination haven't I tried yet?"_
 - _"List all peptide ingredients with purity above 95%."_
 - _"Which botanicals do I source from Madagascar?"_
 - _"Find ingredients where the sequence contains KTTKS."_
@@ -43,7 +44,8 @@ Ask Claude (or another MCP client) things like:
 | `get_test_result` | Full report: every measurement's value, spec, and the **resolved instrument** (`instrumentSource`: row / method / run) |
 | `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 |
+| `get_coverage_matrix` | Which formulations × parameters have been measured (TEST coverage) |
+| `get_design_space` | COMPOSITION design space for one project: which ingredients vary and over what observed wt-% ranges (ranked), an occupied-region summary ("where you've been"), the biggest untested **interior gap** as ready-to-seed DOE ranges (a combination you could have made but skipped), and an optional standardised **2-component PCA** of all varying ingredients — loadings, variance-explained, scree, and a full-dimensional gap. Matches the in-app Design Space Viewer exactly. Answers *"where haven't I explored?"* / *"what should I formulate next?"* |
 | `list_doe_designs` | Saved DOE designs — the *recipe* behind each batch of runs: design type, factors + ranges, constraints, run count, D-efficiency. Filters: `project`, `design_type`, `constrained_only`, `name_contains` |
 | `get_doe_design` | One design in full: constraints in plain language, the model it was optimised for, generation settings (run budget, replicates, centre points, seed) and the complete run matrix with the formulation each run became |
 | `find_by_smarts` | SMARTS-pattern substructure search across every ingredient with a SMILES. Requires `@rdkit/rdkit` (optional dependency — install with `npm install @rdkit/rdkit` in `mcp/` if you get a "not installed" error). Examples: `c1ccccc1` (any aromatic 6-ring), `[OX2H1]` (any hydroxyl), `C(=O)O` (carboxylic acid), `[F,Cl,Br,I]` (any halogen). |
@@ -143,7 +145,7 @@ Or for local-dev (from the repo):
 }
 ```
 
-Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 32 tools become callable in any conversation.
+Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 33 tools become callable in any conversation.
 
 ## Wire it up to Claude Code
 

package/SUBMISSION.md

@@ -47,8 +47,10 @@ _"what parameters fail acceptance most often?"_, or _"show me the DOE matrix
 at sample grain for Anti-Aging Serum family"_ — all against a JSON export
 that stays on the user's laptop.
 
-**15 read-only tools** covering formulations, ingredients, batches, samples,
-test results, DOE matrices, similarity, failure analysis, coverage matrices.
+**33 read-only tools** covering formulations, ingredients, batches, samples,
+test results, DOE matrices + saved designs, similarity, failure analysis,
+test-coverage AND composition design-space mapping (varying ingredients,
+untested gaps, PCA), equipment, test methods, panels, projects and ELN notes.
 
 - Repo: https://github.com/juliu1980/FormLab/tree/main/mcp
 - npm: https://www.npmjs.com/package/formlab-mcp

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 32 tools (see ./tools/) over stdio. The MCP host (Claude
+// Exposes 33 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.
@@ -30,6 +30,7 @@ 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 designspace  from './tools/designspace.js';
 import * as library      from './tools/library.js';
 import * as projects     from './tools/projects.js';
 import * as notebook     from './tools/notebook.js';
@@ -108,6 +109,7 @@ const TOOLS = [
   ...Object.values(ingredients.tools),
   ...Object.values(lab.tools),
   ...Object.values(analytics.tools),
+  ...Object.values(designspace.tools),
   ...Object.values(library.tools),
   ...Object.values(projects.tools),
   ...Object.values(notebook.tools),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "mcpName": "io.github.juliu1980/formlab-mcp",
   "description": "Read-only Model Context Protocol server for FormLab — lets Claude (and other MCP clients) read and analyze your FormLab data, from a local export file OR your live cloud workspace.",
   "type": "module",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.juliu1980/formlab-mcp",
   "description": "Read-only MCP for FormLab — let Claude query your formulation lab. Free reads a local export; Pro connects to your live cloud workspace with a dedicated read-only token.",
-  "version": "0.5.2",
+  "version": "0.6.5",
   "websiteUrl": "https://formvix.com/mcp",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.5.2",
+      "version": "0.6.5",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tools/analytics.js

@@ -508,12 +508,16 @@ const _DOE_TYPE_LABELS = {
 function _doeModelKey(d) {
   return d && d.designType === 'dopt' ? ((d.settings || {}).doptModel || null) : null;
 }
+// A DOE factor is keyed by ingredientId, or by formulationId when it's a
+// sub-formula dosed as a base. Both factors[] and runs[] use that id.
+function _doeFactorId(f) { return f.ingredientId || f.formulationId; }
 // Factor names come off the RECORD first so a design still reads correctly
 // after an ingredient is renamed or deleted.
 function _doeNamer(d, db) {
-  const byId = new Map((d.factors || []).map(f => [f.ingredientId, f.name]));
+  const byId = new Map((d.factors || []).map(f => [_doeFactorId(f), f.name]));
   return (id) => byId.get(id)
     || (((db.ingredients || []).find(i => i.id === id) || {}).name)
+    || (((db.formulations || []).find(x => x.id === id) || {}).name)
     || id || '?';
 }
 function _trimDoeDesign(d, db) {
@@ -528,7 +532,7 @@ function _trimDoeDesign(d, db) {
     project: proj ? proj.name : null,
     runCount: d.runCount || 0,
     factorCount: (d.factors || []).length,
-    factors: (d.factors || []).map(f => ({ ingredient: f.name || nameOf(f.ingredientId), low: f.low, high: f.high, unit: f.unit || '%' })),
+    factors: (d.factors || []).map(f => ({ ingredient: f.name || nameOf(_doeFactorId(f)), low: f.low, high: f.high, unit: f.unit || '%' })),
     constraints: (d.constraints || []).map(c => _doeConstraintText(c, nameOf)),
     mixtureMode: !!d.mixtureMode,
     // The model the design was built for. Lives in settings, so without this a
@@ -663,10 +667,10 @@ const get_doe_design = {
     }
     if (args.include_runs !== false) {
       const facs = d.factors || [];
-      out.factorOrder = facs.map(f => f.name || nameOf(f.ingredientId));
+      out.factorOrder = facs.map(f => f.name || nameOf(_doeFactorId(f)));
       out.runs = (d.runs || []).map((r, i) => {
         const row = { run: i + 1 };
-        facs.forEach(f => { row[f.name || nameOf(f.ingredientId)] = r[f.ingredientId]; });
+        facs.forEach(f => { row[f.name || nameOf(_doeFactorId(f))] = r[_doeFactorId(f)]; });
         const lf = formsById.get((d.formulationIds || [])[i]);
         row.formulation = lf ? (lf.name || lf.uid) : null;
         return row;

package/tools/designspace.js

@@ -0,0 +1,448 @@
+// ============================================================
+// DESIGN-SPACE TOOL — the COMPOSITION-space counterpart to
+// get_coverage_matrix (which reports TEST coverage).
+//
+//   get_design_space   — per project: which ingredients vary and over
+//                         what observed ranges, a summary of the occupied
+//                         region ("where you've been"), the biggest
+//                         untested INTERIOR gap expressed as ingredient
+//                         ranges (ready to seed a DOE), and — optionally —
+//                         a standardised 2-component PCA of ALL varying
+//                         ingredients (loadings + variance-explained + a
+//                         full-dimensional gap).
+//
+// This is a faithful server-side port of the in-app Design Space Viewer
+// (js/views/assembler-designspace.js, shipped v1.15.128–145). The numeric
+// algorithms are copied verbatim so the MCP answer and the on-screen map
+// always agree:
+//   - variation ranking          ← _asmDoeGenFactorCandidates (doegen)
+//   - observed per-ingredient range ← _asmDoeGenObservedRange   (doegen)
+//   - top-3/top-2 interior gap    ← _asmDsComputeGap
+//   - full-dimensional PCA gap    ← _asmDsComputeGapPCA
+//   - standardised 2-component PCA ← _asmDsPCA
+//   - convex hull + point-in-poly  ← _asmDsHull / _asmDsPointInPoly
+//
+// Read-only: it computes over the same DB export every other tool reads;
+// it never mutates anything.
+// ============================================================
+
+import { getStore, resolveById, flattenComposition } from '../data.js';
+
+// ---- composition helper -----------------------------------------------------
+// Ingredient wt-% map for one formula, mirroring the app's _asmIngredientMap:
+//   - a pure-% flat composition (no sub-formulas, every row wt%/%) is taken
+//     VERBATIM (preserves the common "omit the balance-to-100 row" case);
+//   - anything else (absolute units, mixed, or nested) is flattened to true
+//     wt-% via the shared flatten engine, so a leaf reached through a premix
+//     still counts. Returns Map<ingredientId, percent 0–100>.
+function _ingredientPctMap(f) {
+  const out = new Map();
+  if (!f) return out;
+  const comp = (f.composition || []).filter(c => c && (c.ingredientId || c.formulationId));
+  const hasSub = comp.some(c => c.formulationId);
+  const allPct = !hasSub && comp.every(c => {
+    const u = String(c.unit || 'wt%').trim().toLowerCase();
+    return u.startsWith('wt') || u === '%';
+  });
+  if (allPct) {
+    for (const c of comp) {
+      if (!c.ingredientId) continue;
+      const amt = parseFloat(c.amount);
+      out.set(c.ingredientId, (out.get(c.ingredientId) || 0) + (isNaN(amt) ? 0 : amt));
+    }
+    return out;
+  }
+  const flat = flattenComposition(f);   // rows carry weightFraction (0–1)
+  for (const r of flat.rows) {
+    if (!r.ingredientId) continue;
+    const pct = (r.weightFraction || 0) * 100;
+    out.set(r.ingredientId, (out.get(r.ingredientId) || 0) + pct);
+  }
+  // Strip float-precision noise (0.105 + 0.18 = 0.28500000000000003).
+  for (const [k, v] of out) out.set(k, parseFloat(v.toFixed(6)));
+  return out;
+}
+
+// _asmFormulaValueForCol(f, 'ing:'+id) equivalent: the ingredient's wt-% in f,
+// or null when absent (callers coerce null → 0 for the geometry).
+function _ingVal(mapsByForm, f, id) {
+  const m = mapsByForm.get(f.id);
+  const v = m ? m.get(id) : undefined;
+  return (v == null || !Number.isFinite(v)) ? null : v;
+}
+
+// ---- variation ranking (port of _asmDoeGenFactorCandidates, ingredients only) ---
+// A factor is only worth mapping if the data shows it already varies. Score the
+// rest by proportional swing (relative spread) weighted by how broadly they're
+// used, so a pigment ranging 8–14% across many formulas outranks a preservative
+// pinned at 0.2%. Ingredient-only (the design-space view calls with bases off).
+function _factorCandidates(forms, mapsByForm, db) {
+  const byId = new Map();
+  forms.forEach(f => {
+    const map = mapsByForm.get(f.id);
+    if (!map) return;
+    map.forEach((v, id) => {
+      if (v == null || !Number.isFinite(v)) return;
+      if (!byId.has(id)) byId.set(id, []);
+      byId.get(id).push(v);
+    });
+  });
+  const ingName = new Map((db.ingredients || []).map(i => [i.id, i.name]));
+  const cand = [];
+  const scoreOf = (amounts) => {
+    const min = Math.min(...amounts), max = Math.max(...amounts);
+    const spread = max - min;
+    if (spread <= 0.01) return null;              // effectively constant — not a factor
+    const mean = amounts.reduce((a, b) => a + b, 0) / amounts.length;
+    const rel = mean > 0 ? spread / mean : 0;
+    return { obs: { min, max, mean, n: amounts.length }, spread, rel, score: rel * Math.log2(1 + amounts.length) };
+  };
+  byId.forEach((amounts, id) => {
+    if (amounts.length < 2) return;               // need ≥2 uses to see a range
+    const name = ingName.get(id);
+    if (!name) return;                            // ingredient since deleted
+    const s = scoreOf(amounts);
+    if (s) cand.push({ id, name, ...s });
+  });
+  cand.sort((a, b) => b.score - a.score);
+  return cand;
+}
+
+// Observed [min,max,mean,n] for one ingredient across the WHOLE library (global,
+// exactly like _asmDoeGenObservedRange — the PCA gap clamps against it).
+function _observedRange(ingredientId, db, mapsByForm) {
+  if (!ingredientId) return null;
+  const amounts = [];
+  (db.formulations || []).forEach(f => {
+    if (!f || f._trashed) return;
+    const m = mapsByForm.get(f.id) || _ingredientPctMap(f);
+    if (!mapsByForm.has(f.id)) mapsByForm.set(f.id, m);
+    const v = m.get(ingredientId);
+    if (v != null && Number.isFinite(v)) amounts.push(v);
+  });
+  if (!amounts.length) return null;
+  return {
+    min: Math.min(...amounts),
+    max: Math.max(...amounts),
+    mean: amounts.reduce((a, b) => a + b, 0) / amounts.length,
+    n: amounts.length,
+  };
+}
+
+// ---- geometry (verbatim ports) ---------------------------------------------
+// Andrew's monotone-chain convex hull. Input/return: [{x,y}].
+function _hull(pts) {
+  const P = pts.slice().sort((a, b) => a.x - b.x || a.y - b.y);
+  if (P.length < 3) return P;
+  const cross = (o, a, b) => (a.x - o.x) * (b.y - o.y) - (a.y - o.y) * (b.x - o.x);
+  const lower = [];
+  for (const p of P) {
+    while (lower.length >= 2 && cross(lower[lower.length - 2], lower[lower.length - 1], p) <= 0) lower.pop();
+    lower.push(p);
+  }
+  const upper = [];
+  for (let i = P.length - 1; i >= 0; i--) {
+    const p = P[i];
+    while (upper.length >= 2 && cross(upper[upper.length - 2], upper[upper.length - 1], p) <= 0) upper.pop();
+    upper.push(p);
+  }
+  lower.pop(); upper.pop();
+  return lower.concat(upper);
+}
+
+// Ray-casting point-in-polygon.
+function _pointInPoly(x, y, poly) {
+  if (!poly || poly.length < 3) return false;
+  let inside = false;
+  for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+    const xi = poly[i].x, yi = poly[i].y, xj = poly[j].x, yj = poly[j].y;
+    if (((yi > y) !== (yj > y)) && (x < (xj - xi) * (y - yi) / ((yj - yi) || 1e-12) + xi)) inside = !inside;
+  }
+  return inside;
+}
+
+// ---- top-K interior gap (port of _asmDsComputeGap) --------------------------
+// The emptiest reachable spot in ABSOLUTE per-ingredient space + the DOE ranges
+// that bracket it. Working per-axis on each ingredient's own observed range (NOT
+// a normalised simplex) is essential: components can differ 10× in scale, and a
+// normalised gap would seed physically silly levels. `comps` = top-2 or top-3
+// candidates. Returns { mode, abs, factors, interior } or null.
+function _computeGap(mode, comps, forms, mapsByForm) {
+  const K = comps.length;
+  const pts = [];
+  forms.forEach(f => {
+    const comp = comps.map(c => { const v = _ingVal(mapsByForm, f, c.id); return v == null ? 0 : v; });
+    if (comp.every(v => v === 0)) return;
+    pts.push(comp);
+  });
+  if (pts.length < 4) return null;                 // too few points to trust a "gap"
+  const mn = comps.map((_, k) => Math.min(...pts.map(p => p[k])));
+  const mx = comps.map((_, k) => Math.max(...pts.map(p => p[k])));
+  const span = comps.map((_, k) => Math.max(1e-6, mx[k] - mn[k]));
+  const norm = pts.map(p => p.map((v, k) => (v - mn[k]) / span[k]));   // unit-cube coords
+  const M = 0.05;
+  const steps = 12, lo = -M, hiU = 1 + M;
+  const g = (i) => lo + (hiU - lo) * i / steps;
+  const grid = [];
+  if (K === 3) { for (let i = 0; i <= steps; i++) for (let j = 0; j <= steps; j++) for (let l = 0; l <= steps; l++) grid.push([g(i), g(j), g(l)]); }
+  else { for (let i = 0; i <= steps; i++) for (let j = 0; j <= steps; j++) grid.push([g(i), g(j)]); }
+  const dist = (u) => { let dmin = Infinity; for (const n of norm) { let d = 0; for (let k = 0; k < K; k++) { const dd = n[k] - u[k]; d += dd * dd; } if (d < dmin) dmin = d; } return dmin; };
+  // "Bracketed" = real formulas sit on BOTH sides on every axis — a genuine
+  // INTERIOR void, not a frontier extrapolation.
+  const bracketed = (u) => {
+    for (let k = 0; k < K; k++) {
+      let below = false, above = false;
+      for (const n of norm) { if (n[k] < u[k] - 1e-9) below = true; else if (n[k] > u[k] + 1e-9) above = true; if (below && above) break; }
+      if (!(below && above)) return false;
+    }
+    return true;
+  };
+  // For the 2-D case, ALSO require the gap inside the (shrunk) hull, so it can't
+  // sit outside a slanted/correlated cloud.
+  let insideHull = () => true;
+  if (K === 2) {
+    const hull = _hull(norm.map(p => ({ x: p[0], y: p[1] })));
+    if (hull.length >= 3) {
+      let hcx = 0, hcy = 0; hull.forEach(p => { hcx += p.x; hcy += p.y; }); hcx /= hull.length; hcy /= hull.length;
+      const sh = hull.map(p => ({ x: hcx + (p.x - hcx) * 0.85, y: hcy + (p.y - hcy) * 0.85 }));
+      insideHull = (u) => _pointInPoly(u[0], u[1], sh);
+    }
+  }
+  let best = null, bestD = -1, interior = false;
+  for (const u of grid) { if (!bracketed(u) || !insideHull(u)) continue; const d = dist(u); if (d > bestD) { bestD = d; best = u; interior = true; } }
+  if (!best) { for (const u of grid) { const d = dist(u); if (d > bestD) { bestD = d; best = u; } } }
+  if (!best) return null;
+  const abs = comps.map((_, k) => {
+    const t = mn[k] + best[k] * span[k];
+    return Math.min(mx[k] + M * span[k], Math.max(Math.max(0, mn[k] - M * span[k]), t));
+  });
+  const factors = comps.map((c, k) => {
+    const hw = Math.max(0.25, span[k] * 0.3);       // a real design width, not a point
+    return { id: c.id, low: Math.max(0, +(abs[k] - hw).toFixed(3)), high: +(abs[k] + hw).toFixed(3), unit: '%' };
+  });
+  return { mode, abs, factors, interior };
+}
+
+// ---- standardised 2-component PCA (port of _asmDsPCA) -----------------------
+// Each ingredient z-scored first so a 14% filler and a 0.9% dispersant get equal
+// say. Power iteration + deflation (no libraries), fixed seed → deterministic.
+function _pca(forms, ids, mapsByForm) {
+  const n = ids.length; if (n < 2) return null;
+  const rows = [];
+  forms.forEach(f => { const v = ids.map(id => { const x = _ingVal(mapsByForm, f, id); return x == null ? 0 : x; }); rows.push({ f, v }); });
+  const m = rows.length; if (m < 3) return null;
+  const mean = ids.map((_, j) => rows.reduce((s, r) => s + r.v[j], 0) / m);
+  const std = ids.map((_, j) => { const mu = mean[j]; const varj = rows.reduce((s, r) => s + (r.v[j] - mu) ** 2, 0) / Math.max(1, m - 1); return Math.sqrt(varj) || 1; });
+  const Z = rows.map(r => r.v.map((x, j) => (x - mean[j]) / std[j]));
+  const C = Array.from({ length: n }, () => new Array(n).fill(0));
+  for (let a = 0; a < n; a++) for (let b = a; b < n; b++) { let s = 0; for (let i = 0; i < m; i++) s += Z[i][a] * Z[i][b]; s /= Math.max(1, m - 1); C[a][b] = s; C[b][a] = s; }
+  const matVec = (Mx, x) => Mx.map(row => row.reduce((s, e, k) => s + e * x[k], 0));
+  const normalize = (x) => { const l = Math.sqrt(x.reduce((s, e) => s + e * e, 0)) || 1; return x.map(e => e / l); };
+  const power = (Mx) => { let v = normalize(ids.map((_, i) => Math.sin(i + 1.3))); let lam = 0; for (let it = 0; it < 90; it++) { const wv = matVec(Mx, v); const l = Math.sqrt(wv.reduce((s, e) => s + e * e, 0)) || 1; const vn = wv.map(e => e / l); let diff = 0; for (let k = 0; k < n; k++) diff += Math.abs(vn[k] - v[k]); v = vn; lam = l; if (diff < 1e-9) break; } return { vec: v, val: lam }; };
+  const K = Math.min(n, 6);
+  const comps = []; let Mx = C;
+  for (let c = 0; c < K; c++) { const pc = power(Mx); comps.push(pc); Mx = Mx.map((row, a) => row.map((e, b) => e - pc.val * pc.vec[a] * pc.vec[b])); }
+  const pc1 = comps[0], pc2 = comps[1] || comps[0];
+  const trace = C.reduce((s, row, a) => s + row[a], 0) || 1;
+  const varAll = comps.map(pc => Math.max(0, pc.val) / trace);
+  const project = (vabs) => { const z = vabs.map((x, j) => (x - mean[j]) / std[j]); return [z.reduce((s, e, k) => s + e * pc1.vec[k], 0), z.reduce((s, e, k) => s + e * pc2.vec[k], 0)]; };
+  const invProject = (x, y) => ids.map((_, k) => mean[k] + (x * pc1.vec[k] + y * pc2.vec[k]) * std[k]);
+  const scores = rows.map(r => project(r.v));
+  return { ids, rows, scores, project, invProject, load1: pc1.vec, load2: pc2.vec, varAll, var1: varAll[0] || 0, var2: varAll[1] || 0 };
+}
+
+// The ingredients each PC is "made of", biggest |weight| first, with sign.
+function _topLoadings(pca, which, count, db) {
+  const vec = which === 1 ? pca.load1 : pca.load2;
+  const nm = new Map((db.ingredients || []).map(i => [i.id, i.name]));
+  return pca.ids.map((id, k) => ({ ingredient: nm.get(id) || id, id, weight: +vec[k].toFixed(4) }))
+    .sort((a, b) => Math.abs(b.weight) - Math.abs(a.weight)).slice(0, count || 5);
+}
+
+// ---- full-dimensional PCA gap (port of _asmDsComputeGapPCA) -----------------
+// The emptiest INTERIOR spot in the standardised PCA plane, mapped back to real
+// ingredient levels and clamped to each ingredient's observed range so the
+// seeded DOE stays realistic. Returns { score, factors, interior } or null.
+function _computeGapPCA(pca, db, mapsByForm) {
+  const scores = pca.scores; if (scores.length < 4) return null;
+  const xs = scores.map(s => s[0]), ys = scores.map(s => s[1]);
+  const xMin = Math.min(...xs), xMax = Math.max(...xs), yMin = Math.min(...ys), yMax = Math.max(...ys);
+  const sx = (xMax - xMin) || 1, sy = (yMax - yMin) || 1, G = 22;
+  const dist = (x, y) => { let mn = Infinity; for (const s of scores) { const dx = (s[0] - x) / sx, dy = (s[1] - y) / sy; const dd = dx * dx + dy * dy; if (dd < mn) mn = dd; } return mn; };
+  const hull = _hull(scores.map(s => ({ x: s[0], y: s[1] })));
+  let hcx = 0, hcy = 0; hull.forEach(p => { hcx += p.x; hcy += p.y; }); hcx /= (hull.length || 1); hcy /= (hull.length || 1);
+  const shrunk = hull.map(p => ({ x: hcx + (p.x - hcx) * 0.82, y: hcy + (p.y - hcy) * 0.82 }));
+  const scan = (poly) => { let b = null, bd = -1; for (let i = 0; i <= G; i++) for (let j = 0; j <= G; j++) { const x = xMin + sx * i / G, y = yMin + sy * j / G; if (poly && !_pointInPoly(x, y, poly)) continue; const dd = dist(x, y); if (dd > bd) { bd = dd; b = [x, y]; } } return b; };
+  let best = scan(shrunk), interior = !!best;
+  if (!best) { best = scan(hull); interior = false; }
+  if (!best) { best = scan(null); interior = false; }
+  if (!best) return null;
+  const abs = pca.invProject(best[0], best[1]);
+  const factors = pca.ids.map((id, k) => { const obs = _observedRange(id, db, mapsByForm) || { min: 0, max: 100 }; const hw = Math.max(0.25, (obs.max - obs.min) * 0.3); const t = Math.min(obs.max + hw, Math.max(0, abs[k])); return { id, low: Math.max(0, +(t - hw).toFixed(3)), high: +(t + hw).toFixed(3), unit: '%' }; });
+  return { score: best, factors, interior };
+}
+
+// ---- eligibility: projects worth mapping (≥3 formulas) ----------------------
+function _eligibleProjects(db) {
+  const counts = new Map();
+  (db.formulations || []).forEach(f => { if (f && !f._trashed && f.projectId) counts.set(f.projectId, (counts.get(f.projectId) || 0) + 1); });
+  const out = [];
+  (db.projects || []).forEach(p => { const n = counts.get(p.id) || 0; if (n >= 3) out.push({ id: p.id, name: p.name || p.id, n }); });
+  out.sort((a, b) => b.n - a.n);
+  return out;
+}
+
+const get_design_space = {
+  definition: {
+    name: 'get_design_space',
+    description: 'Map a project\'s COMPOSITION design space (the descriptive mirror of the DOE designer, and the composition-space counterpart to get_coverage_matrix\'s TEST coverage). For one project it returns: the ingredients that actually VARY across its formulas + their observed wt-% ranges (ranked by proportional swing); an occupied-region summary ("where you\'ve been"); the biggest untested INTERIOR gap — a combination you could have made but skipped, kept inside the occupied cloud — expressed as ready-to-seed DOE ingredient ranges (low/high %); and, when the project has ≥3 varying ingredients, a standardised 2-component PCA of ALL of them: per-axis ingredient loadings, variance-explained, a scree list, and a full-dimensional gap. Numbers match FormLab\'s in-app Design Space Viewer exactly. Use it to answer "where haven\'t I explored?" / "what should I formulate next?" and to hand a chemist an experiment target. Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Project id, UID, or name (case-insensitive; substring allowed). Omit to auto-pick the most-populated eligible project (≥3 formulas).' },
+        include_pca: { type: 'boolean', description: 'Include the "map everything" PCA of all varying ingredients (loadings + variance + full-dimensional gap). Default true. Needs ≥3 varying ingredients and ≥3 formulas.' },
+        loadings_per_component: { type: 'number', description: 'How many top ingredient loadings to list per principal component. Default 5, max 20.' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const norm = (s) => String(s || '').toLowerCase();
+
+    // Resolve the project (explicit pick, else the most-populated eligible one).
+    let proj = null;
+    if (args.project) {
+      proj = resolveById('projects', args.project)
+        || (db.projects || []).find(p => norm(p.name) === norm(args.project))
+        || (db.projects || []).find(p => norm(p.name).includes(norm(args.project)));
+      if (!proj) return { error: `No project matched "${args.project}".` };
+    } else {
+      const elig = _eligibleProjects(db);
+      if (!elig.length) return { error: 'No project has ≥3 formulas to map. Assign at least 3 formulas to a project first.' };
+      proj = (db.projects || []).find(p => p.id === elig[0].id);
+    }
+    const pid = proj.id;
+    const forms = (db.formulations || []).filter(f => f && !f._trashed && f.projectId === pid);
+
+    // Precompute ingredient maps once (reused by ranking, gap, PCA, observed range).
+    const mapsByForm = new Map(forms.map(f => [f.id, _ingredientPctMap(f)]));
+
+    const out = {
+      project: { id: pid, uid: proj.uid || null, name: proj.name || pid, formulaCount: forms.length },
+      notes: [],
+    };
+    if (forms.length < 3) {
+      out.notes.push('This project has fewer than 3 formulas — a design space is only coherent with at least 3 points. Results below are provisional.');
+    }
+
+    // Varying ingredients + observed ranges (ranked).
+    const cand = _factorCandidates(forms, mapsByForm, db);
+    out.varyingIngredientCount = cand.length;
+    out.varyingIngredients = cand.map(c => ({
+      ingredient: c.name,
+      id: c.id,
+      observedRange: { min: +c.obs.min.toFixed(4), max: +c.obs.max.toFixed(4), mean: +c.obs.mean.toFixed(4), unit: '%', usedInFormulas: c.obs.n },
+      relativeSpread: +c.rel.toFixed(4),
+      variationScore: +c.score.toFixed(4),
+    }));
+
+    if (cand.length < 2) {
+      out.notes.push(`Only ${cand.length} ingredient${cand.length === 1 ? '' : 's'} vary across this project — a space needs at least 2 that change from formula to formula. Nothing to map yet.`);
+      out.axes = null;
+      out.occupiedRegion = null;
+      out.gap = null;
+      return out;
+    }
+
+    // Axes: top-3 ternary (relative proportions) or top-2 scatter (absolute %).
+    const mode = cand.length >= 3 ? 'ternary' : 'scatter';
+    const comps = cand.slice(0, mode === 'ternary' ? 3 : 2);
+    out.axes = {
+      mode,
+      basis: mode === 'ternary'
+        ? 'Top 3 most-varying ingredients, as relative proportions (a ternary).'
+        : 'Top 2 most-varying ingredients, as absolute wt-%.',
+      ingredients: comps.map(c => c.name),
+    };
+
+    // Occupied-region summary: the bounding envelope of the plotted axes + how
+    // many formulas actually sit in the space. The app draws the convex hull of
+    // these points; the per-axis min/max here is that hull's bounding box.
+    let inSpace = 0;
+    forms.forEach(f => { if (comps.some(c => _ingVal(mapsByForm, f, c.id) != null)) inSpace++; });
+    out.occupiedRegion = {
+      formulaPoints: inSpace,
+      axisRanges: comps.map(c => ({ ingredient: c.name, id: c.id, min: +c.obs.min.toFixed(4), max: +c.obs.max.toFixed(4), unit: '%' })),
+      note: 'Bounding envelope of the observed compositions on the mapped axes. In the app this is the shaded convex hull ("where you\'ve been"); the untested gap below was found INSIDE that occupied cloud, not on its frontier.',
+    };
+
+    // The top untested interior gap, as ready-to-seed DOE ranges.
+    const gap = _computeGap(mode, comps, forms, mapsByForm);
+    if (!gap) {
+      out.gap = null;
+      out.notes.push('Too few distinct formula points (need ≥4 with these axes) to locate a trustworthy gap.');
+    } else {
+      out.gap = {
+        interior: gap.interior,
+        basis: `${mode === 'ternary' ? 'top-3' : 'top-2'} varying ingredients`,
+        target: comps.map((c, k) => ({
+          ingredient: c.name,
+          id: c.id,
+          center: +gap.abs[k].toFixed(3),
+          low: gap.factors[k].low,
+          high: gap.factors[k].high,
+          unit: '%',
+        })),
+        note: gap.interior
+          ? 'Interior void: real formulas bracket this point on every axis — a combination you could have made but skipped. The low/high ranges are ready to seed a DOE.'
+          : 'Frontier point (fallback): the cluster was too thin to bracket a true interior void, so this is the farthest-from-any-formula point — an extrapolation; sanity-check before running.',
+      };
+    }
+
+    // Optional: PCA over ALL varying ingredients.
+    const wantPca = args.include_pca !== false;
+    if (wantPca && cand.length >= 3 && forms.length >= 3) {
+      const ids = cand.map(c => c.id);
+      const pca = _pca(forms, ids, mapsByForm);
+      if (pca) {
+        const nLoad = Math.min(20, Math.max(1, args.loadings_per_component || 5));
+        const varPct = Math.round((pca.var1 + pca.var2) * 100);
+        const pcaOut = {
+          ingredientCount: ids.length,
+          varianceExplained: { pc1: +pca.var1.toFixed(4), pc2: +pca.var2.toFixed(4), cumulative: +((pca.var1 + pca.var2)).toFixed(4) },
+          components: [
+            { component: 1, varianceExplained: +pca.var1.toFixed(4), loadings: _topLoadings(pca, 1, nLoad, db) },
+            { component: 2, varianceExplained: +pca.var2.toFixed(4), loadings: _topLoadings(pca, 2, nLoad, db) },
+          ],
+          scree: pca.varAll.map((v, i) => ({ component: i + 1, varianceExplained: +v.toFixed(4) })),
+          note: 'Axes are ingredient combinations, not single ingredients — read the loadings to interpret them. + weight means the ingredient increases toward that axis\'s positive end. Each ingredient is standardised (z-scored) first, so a trace dispersant and a bulk filler get equal say.',
+        };
+        if (varPct < 60) pcaOut.warning = `PC1+PC2 hold only ${varPct}% of the variation — a rough overview; structure may live in components not shown (see scree).`;
+        const gapPca = _computeGapPCA(pca, db, mapsByForm);
+        if (gapPca) {
+          pcaOut.gap = {
+            interior: gapPca.interior,
+            dimensionality: 'full (all varying ingredients)',
+            target: gapPca.factors.map(fac => {
+              const c = cand.find(x => x.id === fac.id);
+              return { ingredient: c ? c.name : fac.id, id: fac.id, low: fac.low, high: fac.high, unit: '%' };
+            }),
+            note: gapPca.interior
+              ? 'Full-dimensional interior void: emptiest spot inside the occupied PCA cloud, mapped back to real ingredient levels and clamped to each ingredient\'s observed range. Ready to seed a DOE across all varying ingredients.'
+              : 'Frontier fallback (not a bracketed interior void) — sanity-check before running.',
+          };
+        }
+        out.pca = pcaOut;
+      }
+    } else if (wantPca) {
+      out.notes.push(`PCA needs ≥3 varying ingredients and ≥3 formulas (have ${cand.length} varying, ${forms.length} formulas) — skipped.`);
+    }
+
+    if (!out.notes.length) delete out.notes;
+    return out;
+  },
+};
+
+export const tools = {
+  get_design_space,
+};