formlab-mcp 0.5.1 → 0.6.0

package/README.md

@@ -40,10 +40,12 @@ Ask Claude (or another MCP client) things like:
 | `list_samples` | Filtered list of physical specimens |
 | `get_sample` | Full record + canonical variant + test reports + blend lineage |
 | `list_test_results` | Filtered list of test reports (by sample, parameter, **measured-value range** (`value_min`/`value_max`), date, or lab) |
-| `get_test_result` | Full record + every measurement value |
+| `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 |
+| `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.1' },
+  { name: 'formlab-mcp', version: '0.6.0' },
   { capabilities: { tools: {} } }
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formlab-mcp",
-  "version": "0.5.1",
+  "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/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.1",
+  "version": "0.5.2",
   "websiteUrl": "https://formvix.com/mcp",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.5.1",
+      "version": "0.5.2",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tools/analytics.js

@@ -5,10 +5,40 @@
 //   - 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';
 
+// Which instrument produced a measurement. Mirrors the app's _trMeasInstrument:
+// a measurement's raw `instrument` is usually EMPTY because blank means inherit,
+// so returning the stored field alone would be near-useless here. Resolve the
+// same cascade the UI shows, and report the source so a consumer can tell a
+// recorded fact from an inherited default:
+//   'row'    — the measurement names its own instrument
+//   'method' — from the parameter's Test Method equipment (the usual case)
+//   'run'    — the report-level default (an assumption, not evidence)
+function _resolveInstrument(m, t, db) {
+  if (m && (m.instrument || m.equipmentId)) {
+    return { instrument: m.instrument || '', equipmentId: m.equipmentId || null, instrumentSource: 'row' };
+  }
+  const params = (db && db.parameters) || [];
+  let pm = null;
+  if (m && m.parameterId) pm = params.find(p => p && p.id === m.parameterId) || null;
+  if (!pm && m) {
+    const nm = String(m.parameter || '').trim().toLowerCase();
+    if (nm) pm = params.find(p => p && String(p.name || '').trim().toLowerCase() === nm) || null;
+  }
+  if (pm && (pm.equipment || pm.equipmentId)) {
+    return { instrument: pm.equipment || '', equipmentId: pm.equipmentId || null, instrumentSource: 'method' };
+  }
+  if (t && (t.instrument || t.equipmentId)) {
+    return { instrument: t.instrument || '', equipmentId: t.equipmentId || null, instrumentSource: 'run' };
+  }
+  return { instrument: '', equipmentId: null, instrumentSource: null };
+}
+
 function _trimTest(t, samplesById) {
   if (!t) return null;
   const s = t.sampleId ? samplesById.get(t.sampleId) : null;
@@ -20,12 +50,16 @@ function _trimTest(t, samplesById) {
     testDate: t.testDate || '',
     performedBy: t.performedBy || '',
     lab: t.lab || '',
+    instrument: t.instrument || '',          // run-level default; measurements may override
+    equipmentId: t.equipmentId || null,
+    controlSample: !!t.controlSample,        // a re-measured reference — the valid basis for drift
     measurementCount: (t.measurements || []).length,
     parameters: [...new Set((t.measurements || []).map(m => m.parameter).filter(Boolean))],
   };
 }
 
-function _trimMeasurement(m) {
+function _trimMeasurement(m, t, db) {
+  const ins = _resolveInstrument(m, t, db);
   return {
     parameter: m.parameter || '',
     value: m.value ?? null,
@@ -34,13 +68,14 @@ function _trimMeasurement(m) {
     pointCount: Array.isArray(m.points) ? m.points.length : 0,
     binCount: Array.isArray(m.bins) ? m.bins.length : 0,
     acceptanceCriteria: m.acceptanceCriteria || null,
+    ...ins,                                   // instrument, equipmentId, instrumentSource
   };
 }
 
 const list_test_results = {
   definition: {
     name: 'list_test_results',
-    description: 'List test result reports, optionally filtered by sample, parameter, measured-value range, date range, or lab. Combine parameter + value_min/value_max to find reports whose measurement is in range (the "find by results" query, e.g. parameter="Viscosity", value_min=800, value_max=3000). Returns metadata + parameters tested; use get_test_result for full measurement values.',
+    description: 'List test result reports, optionally filtered by sample, parameter, measured-value range, date range, or lab. Combine parameter + value_min/value_max to find reports whose measurement is in range (the "find by results" query, e.g. parameter="Viscosity", value_min=800, value_max=3000). Returns metadata (incl. the run-level instrument and controlSample flag) + parameters tested; use get_test_result for per-measurement values and their resolved instruments.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -99,7 +134,7 @@ const list_test_results = {
 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.',
+    description: 'Get full details for a single test result report: every measurement\'s value, unit, type, acceptance criteria, and the INSTRUMENT that produced it. instrument is RESOLVED (measurement override → the parameter\'s Test Method equipment → the report default) with instrumentSource telling you which — treat source "run" as an inherited assumption, not evidence. Accepts internal id or UID.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -115,7 +150,7 @@ const get_test_result = {
     return {
       ..._trimTest(t, indexes.samplesById),
       notes: t.notes || '',
-      measurements: (t.measurements || []).map(_trimMeasurement),
+      measurements: (t.measurements || []).map(m => _trimMeasurement(m, t, getStore().db)),
     };
   },
 };
@@ -430,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,
 };