formlab-mcp 0.5.2 → 0.6.0

package/README.md

@@ -44,6 +44,8 @@ Ask Claude (or another MCP client) things like:
 | `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 |
+| `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). |
 | `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) |
@@ -141,7 +143,7 @@ Or for local-dev (from the repo):
 }
 ```
 
-Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 30 tools become callable in any conversation.
+Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 32 tools become callable in any conversation.
 
 ## Wire it up to Claude Code
 

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 30 tools (see ./tools/) over stdio. The MCP host (Claude
+// Exposes 32 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.
@@ -114,7 +114,7 @@ const TOOLS = [
 ];
 
 const server = new Server(
-  { name: 'formlab-mcp', version: '0.5.2' },
+  { name: 'formlab-mcp', version: '0.6.0' },
   { capabilities: { tools: {} } }
 );
 

package/package.json

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

package/tools/analytics.js

@@ -5,6 +5,8 @@
 //   - 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)
+//   - list_doe_designs       (saved design records — the intent behind the runs)
+//   - get_doe_design         (one design in full, incl. its run matrix)
 // ============================================================
 
 import { getStore, resolveById, flattenComposition } from '../data.js';
@@ -463,10 +465,187 @@ const get_coverage_matrix = {
   },
 };
 
+// ============================================================
+// SAVED DOE DESIGNS
+// ------------------------------------------------------------
+// get_doe_matrix reconstructs an EXECUTED design after the fact from
+// formulations + tests. These two read the design RECORD instead: the factors
+// and their ranges, the constraints, the model the runs were optimised for, the
+// run budget, the seed and the resulting D-efficiency — the intent behind the
+// runs, which cannot be recovered from the runs themselves.
+// ============================================================
+
+// Human-readable constraint, e.g. "Water + Glycerin <= 40". Mirrors the app's
+// _asmDoeConstraintLabel, including its ratio special case, so the MCP never
+// describes a rule differently from the UI.
+function _doeConstraintText(c, nameOf) {
+  if (c && c.ratioGroup && c.ratioRole && (c.terms || []).length === 2) {
+    const bound = -(+c.terms[1].coef || 0);
+    return `${nameOf(c.terms[0].id)} : ${nameOf(c.terms[1].id)} ${c.ratioRole === 'lo' ? 'at least' : 'at most'} ${+bound.toFixed(6)}:1`;
+  }
+  const parts = ((c && c.terms) || []).map((t, i) => {
+    const coef = +t.coef || 0;
+    const mag = Math.abs(coef);
+    return `${coef < 0 ? '- ' : (i ? '+ ' : '')}${mag === 1 ? '' : +mag.toFixed(6) + '*'}${nameOf(t.id)}`;
+  });
+  const op = c && c.op === '>=' ? '>=' : c && c.op === '==' ? '=' : '<=';
+  return `${parts.join(' ')} ${op} ${+(+(c && c.rhs) || 0).toFixed(6)}`;
+}
+const _DOE_MODEL_LABELS = {
+  linear: 'Linear (main effects)',
+  quadratic: 'Quadratic',
+  'quadratic-int': 'Quadratic + interactions (full response surface)',
+  'scheffe-linear': 'Scheffé linear (mixture — no intercept)',
+  'scheffe-quadratic': 'Scheffé quadratic (mixture — adds two-way blending terms)',
+  'scheffe-cubic': 'Scheffé special cubic (mixture — adds three-way blending terms)',
+};
+const _DOE_TYPE_LABELS = {
+  full: 'Full-factorial', pb: 'Plackett-Burman', ccd: 'Central Composite',
+  bbd: 'Box-Behnken', lhs: 'Latin Hypercube', simplex: 'Simplex-Lattice', dopt: 'D-optimal',
+};
+// 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]));
+  return (id) => byId.get(id)
+    || (((db.ingredients || []).find(i => i.id === id) || {}).name)
+    || id || '?';
+}
+function _trimDoeDesign(d, db) {
+  const nameOf = _doeNamer(d, db);
+  const proj = d.projectId ? (db.projects || []).find(p => p.id === d.projectId) : null;
+  return {
+    id: d.id,
+    uid: d.uid,
+    name: d.name,
+    designType: d.designType,
+    designTypeLabel: _DOE_TYPE_LABELS[d.designType] || d.designType,
+    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 || '%' })),
+    constraints: (d.constraints || []).map(c => _doeConstraintText(c, nameOf)),
+    mixtureMode: !!d.mixtureMode,
+    // Only D-optimal computes one; null here means "not applicable", not "failed".
+    dEfficiency: Number.isFinite(d.dEfficiency) ? +d.dEfficiency.toFixed(2) : null,
+    droppedRuns: d.droppedRuns || 0,
+    response: d.responseText || null,
+    createdAt: d.createdAt,
+  };
+}
+
+const list_doe_designs = {
+  definition: {
+    name: 'list_doe_designs',
+    description: 'List saved DOE designs — the recipe behind each generated batch of runs: design type, factors and their ranges, constraints, run count and D-efficiency. This is the design INTENT; use get_doe_matrix for the executed runs and their measured results. Use get_doe_design for the full run matrix of one design.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Filter by project name or id.' },
+        design_type: { type: 'string', description: 'Filter by design type: full, pb, ccd, bbd, lhs, simplex, dopt.' },
+        constrained_only: { type: 'boolean', description: 'Only designs that carry linear constraints.' },
+        name_contains: { type: 'string', description: 'Case-insensitive substring match on design 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 norm = (s) => String(s || '').toLowerCase();
+    const all = (db.doeDesigns || []).filter(d => d && !d._trashed);
+    const filtered = all.filter(d => {
+      if (args.design_type && norm(d.designType) !== norm(args.design_type)) return false;
+      if (args.constrained_only && !(d.constraints || []).length) return false;
+      if (args.name_contains && !norm(d.name).includes(norm(args.name_contains))) return false;
+      if (args.project) {
+        const p = indexes.projectsById.get(args.project)
+          || (db.projects || []).find(x => norm(x.name) === norm(args.project));
+        if (!p || d.projectId !== p.id) return false;
+      }
+      return true;
+    }).sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')));
+    return {
+      totalMatching: filtered.length,
+      returned: Math.min(filtered.length, limit),
+      doeDesigns: filtered.slice(0, limit).map(d => _trimDoeDesign(d, db)),
+    };
+  },
+};
+
+const get_doe_design = {
+  definition: {
+    name: 'get_doe_design',
+    description: 'Get one saved DOE design in full: factors and ranges, constraints, the model it was optimised for, generation settings (run budget, replicates, centre points, seed), D-efficiency, and the complete run matrix with the formulation each run became. Everything needed to reproduce or audit the design.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        design: { type: 'string', description: 'Design id or UID (e.g. "DOE-0001").' },
+        include_runs: { type: 'boolean', description: 'Include the full run matrix. Default true.' },
+      },
+      required: ['design'],
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const d = resolveById('doeDesigns', args.design);
+    if (!d) return { error: `No DOE design matched "${args.design}".` };
+    const nameOf = _doeNamer(d, db);
+    const base = _trimDoeDesign(d, db);
+    const st = d.settings || {};
+    // Only report the settings that actually apply to this design type —
+    // an axial distance on a Plackett-Burman would be noise presented as fact.
+    const settings = { replicates: st.replicates };
+    if (d.designType === 'dopt') {
+      settings.runBudget = st.doptRuns;
+      settings.modelOptimisedFor = _DOE_MODEL_LABELS[st.doptModel] || st.doptModel;
+      // A mixture design is modelled on the simplex, which changes what the
+      // coefficients mean — worth stating rather than leaving to be inferred
+      // from the model name.
+      if (/^scheffe-/.test(String(st.doptModel || ''))) {
+        settings.mixtureNote = 'Scheffé (mixture) model: no intercept and no pure squares, because components summing to a constant make those terms inestimable. Coefficients read as blend effects, not factor effects.';
+      }
+    }
+    if (d.designType === 'lhs') { settings.runBudget = st.nRuns; settings.randomSeed = st.seed; }
+    if (d.designType === 'ccd') { settings.centerPoints = st.centerPoints; settings.axialDistance = st.alpha; }
+    if (d.designType === 'bbd') settings.centerPoints = st.centerPoints;
+    if (d.designType === 'simplex') settings.latticeDegree = st.simplexDegree;
+
+    const formsById = new Map((db.formulations || []).map(f => [f.id, f]));
+    const linked = (d.formulationIds || []).map(id => formsById.get(id)).filter(Boolean);
+    const out = {
+      ...base,
+      balanceFactor: d.mixtureMode ? nameOf(d.balanceFactorId) : null,
+      settings,
+      augmentedFromProjectId: d.augmentedFromProjectId || null,
+      formulationsGenerated: (d.formulationIds || []).length,
+      formulationsStillPresent: linked.length,
+      notes: d.notes || null,
+    };
+    if (Number.isFinite(d.dEfficiency)) {
+      out.dEfficiencyNote = 'D-efficiency compares designs fitting the SAME model at the SAME run count. It is a relative score, not a pass mark, and cannot be compared across different models.';
+    }
+    if (args.include_runs !== false) {
+      const facs = d.factors || [];
+      out.factorOrder = facs.map(f => f.name || nameOf(f.ingredientId));
+      out.runs = (d.runs || []).map((r, i) => {
+        const row = { run: i + 1 };
+        facs.forEach(f => { row[f.name || nameOf(f.ingredientId)] = r[f.ingredientId]; });
+        const lf = formsById.get((d.formulationIds || [])[i]);
+        row.formulation = lf ? (lf.name || lf.uid) : null;
+        return row;
+      });
+    }
+    return out;
+  },
+};
+
 export const tools = {
   list_test_results,
   get_test_result,
   get_doe_matrix,
   find_failures,
   get_coverage_matrix,
+  list_doe_designs,
+  get_doe_design,
 };