formlab-mcp 0.6.48 → 0.6.50

package/README.md

@@ -30,18 +30,18 @@ Ask Claude (or another MCP client) things like:
 | Tool | Purpose |
 |---|---|
 | `list_formulations` | Filtered list of recipes |
-| `get_formulation` | Full record + flattened wt-% composition (sub-formulas expanded), the ordered **step procedure**, user **custom fields**, any **process-factor values** (DOE inputs — cure temp, mix time, RPM, pH…), and the declared **finishedDensity** (g/mL of the mixed product; volume-targeted batches scale by it) |
+| `get_formulation` | Full record + flattened wt-% composition (sub-formulas expanded), the ordered **step procedure**, user **custom fields**, any **process-factor values** (DOE inputs — cure temp, mix time, RPM, pH…), the declared **finishedDensity** (g/mL of the mixed product; volume-targeted batches scale by it), and its **theoretical parameters computed** the way the app's Params tab does (Energy kcal/100g, NV %, Cost/kg…: value, unit, formula, spec pass/fail, and a `warning` when ingredients lack a value or carry mixed units) — the app's own engine, vendored in `mcp/vendor/` and run in an isolated `node:vm` context |
 | `find_similar_formulations` | Find formulas using a given ingredient ≥ threshold % |
 | `compare_formulations` | Pairwise side-by-side composition diff |
 | `list_ingredients` | Filtered list of raw materials. Filters: `family`, `supplier`, `name_contains`, `in_stock_only`, `ingredient_class` (small-molecule / surfactant / polymer / extract / fragrance / pigment / sequence / mixture), `sequence_contains` (e.g. `KTTKS` → Matrixyl), `taxon_contains` (e.g. `Centella`) |
-| `get_ingredient` | Full record + supplier / **cost ($/kg)** / stock / chemical name / molecular weight / storage / formulations using it, plus **GHS safety** (pictograms, H/P codes, signal word), **per-jurisdiction regulatory status**, **approved sources** (the suppliers / manufacturers qualified to supply this material — ASL/AML), and **inventory lots** (balances + expiry + the source each was received from). Returns every class-specific sub-object when present: `sequence` (peptide / oligo), `taxon` (NCBI ID + scientific name), `ingredientClass`, `extractDetails`, `sequenceDetails`, `polymerDetails`, `surfactantDetails`, `pigmentDetails`, `fragranceDetails` |
+| `get_ingredient` | Full record + supplier / **cost ($/kg)** / stock / chemical name / molecular weight / storage / formulations using it, plus **GHS safety** (pictograms, H/P codes, signal word), **per-jurisdiction regulatory status**, **approved sources** (the suppliers / manufacturers qualified to supply this material — ASL/AML), and **inventory lots** (balances + expiry + the source each was received from). Returns every class-specific sub-object when present: `sequence` (peptide / oligo), `taxon` (NCBI ID + scientific name), `ingredientClass`, `extractDetails`, `sequenceDetails`, `polymerDetails`, `surfactantDetails`, `pigmentDetails`, `fragranceDetails`, and its **custom fields** with units (`customFields`: protein / carb / fat in g/100g, solids %… — what theoretical parameters read) |
 | `list_lots` | Inventory lots across ingredients (each a received batch with its own remaining balance, supplier, expiry, **unit cost**, **status** — `active` / `hold` / `quarantine` / `rejected`; held lots are blocked from consumption, with a `holdReason` — and the **approved source** it was received from: `source.supplier` + `source.manufacturer`, where recalls hinge on the manufacturer). Each lot also reports its **Certificate of Analysis** (`coa`: linked, or matched by lot number) and `coaMissing` for an in-stock lot without one. Filters: `ingredient_id`, `expiring_within_days`, `status` (e.g. `hold` to find lots held for a recall), `missing_coa` |
 | `list_suppliers` | Supplier / manufacturer records with roll-ups — ingredients approved, lots received / on hand (+ value at paid cost), qualified / trial / disqualified source counts, last receipt; lots count by supplier **and** by manufacturer |
 | `get_supplier` | One supplier in full: record, every ingredient it's an approved source for, every lot from it, and the **recall trace** (batches that consumed those lots → products, shipments, samples, sub-batches; lots on hold flagged) |
 | `list_documents` | The document register (same as the app's Documents page): ingredient SDS / PDS / CoA / other with lot, version, source and expiry; test and notebook attachments; per-record uploads and links (formulas, batches, samples, suppliers, equipment…). File **metadata** only, never the text inside a file, with who added each file (`addedBy`) and when. Filters: `type`, `record`, `linked`, `query`, `lot`, `format`, `expiry`, `expiring_within_days`, `without_expiry`, `uploaded_within_days`, `added_by`. A `summary` block carries the page's tile counts: expired, expiring in 30 days, SDS/CoA without expiry, ingredients missing an SDS (+ coverage %), lots in stock without a CoA, added last 7 days |
 | `list_inventory` | Portfolio stock rollup — one row per ingredient with on-hand qty, summed lot balance, nearest expiry, and a low-stock flag (on-hand ≤ `reorderThreshold`, or zero). Filters: `low_stock_only`, `expiring_within_days`, `family` |
 | `list_batches` | Filtered list of production / lab-prep events |
-| `get_batch` | Full record + actual composition, measured/derived **actual volume** (mass ÷ density, never a sum of per-ingredient volumes) and **actual mass** (yield, else summed as-prepared inputs — mL rows through that ingredient's density — else measured volume × density), **estimatedVolume** (mass ÷ the formula's finished density when no actual exists, flagged `estimate: true`), **plannedMass** for volume-target batches (target × finished density) and **formulaFinishedDensity**, the **process** method + any **process-factor values** (DOE inputs), samples + blend lineage, and — as a finished-goods lot — its storage **`location`** + finished-goods **`stockLedger`** (shipments out + adjustments; `shippedQty` total) |
+| `get_batch` | Full record + actual composition, measured/derived **actual volume** (mass ÷ density, never a sum of per-ingredient volumes) and **actual mass** (yield, else summed as-prepared inputs — mL rows through that ingredient's density — else measured volume × density), **estimatedVolume** (mass ÷ the formula's finished density when no actual exists, flagged `estimate: true`), **plannedMass** for volume-target batches (target × finished density) and **formulaFinishedDensity**, the **process** method + any **process-factor values** (DOE inputs), samples + blend lineage, and — as a finished-goods lot — its storage **`location`** + finished-goods **`stockLedger`** (shipments out + adjustments; `shippedQty` total), and its **theoretical parameters computed on the batch as made** (actual composition when logged — `basis: "actual"` — else the recipe; the batch's own parameter list when it overrides the formula's) |
 | `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` — a curve at its final point, a distribution at its spec's statistic or D50), **grade** (`min_grade`/`max_grade` on a ranked scale), **text value** (`value_equals`), **run condition** (`condition`), date, or lab) |

package/cloud.js

@@ -48,7 +48,7 @@ async function _fetchDb({ url, anonKey, token }) {
   let body = null;
   try { body = await res.json(); } catch { /* non-JSON error page */ }
   if (res.status === 401) {
-    throw new Error('the MCP token was rejected (missing, revoked, or malformed). Reconnect from FormLab → Settings → Account → AI tools (MCP) → Connect, and paste the new FORMLAB_MCP_TOKEN.');
+    throw new Error('the MCP token was rejected: it is missing, revoked or malformed, or the workspace owner has turned off AI tools for members. Reconnect from FormLab → Settings → Account → AI tools (MCP) → Connect, and paste the new FORMLAB_MCP_TOKEN.');
   }
   if (!res.ok || !body || body.ok !== true || !body.db) {
     throw new Error(`MCP endpoint error (HTTP ${res.status})${body && body.error ? ': ' + body.error : ''}`);

package/package.json

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

package/theoretical.js

@@ -0,0 +1,81 @@
+// =====================================================================
+// Theoretical parameters for the MCP server — the app's own engine, not a
+// port. mcp/vendor/ holds exact copies of js/cost.js, js/nesting.js and
+// js/views/theoretical-params.js (test/mcp-theoretical.test.js keeps them
+// identical), so get_formulation reports the same Energy / NV / Cost per kg
+// the Params tab shows, with the same ⚠ notes.
+//
+// They run in a node:vm context that holds ONLY a JSON copy of the data: no
+// host objects (whose prototype chain would lead back to this process), no
+// require, no process. Formulas are shared workspace data and the engine
+// compiles them with new Function; since app build 17m the compiler allows
+// only the formula language's own names (B21). The vm is a second wall, so a
+// formula from someone else's workspace can't reach this machine either way.
+// =====================================================================
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+
+const VENDOR = new URL('./vendor/', import.meta.url);
+const FILES = ['cost.js', 'nesting.js', 'theoretical-params.js'];
+let _source = null;
+function source() {
+  if (!_source) _source = FILES.map(f => readFileSync(new URL(f, VENDOR), 'utf8')).join('\n;\n');
+  return _source;
+}
+
+// Runs inside the vm: evaluates one formulation's (or batch's) parameters and
+// returns a JSON string, so only plain text crosses back.
+const EPILOGUE = `
+;function __theo(kind, id) {
+  var coll = kind === 'batch' ? db.batches : db.formulations;
+  var e = (coll || []).find(function (x) { return x && x.id === id; });
+  if (!e) return '[]';
+  var params = _tpEffectiveParams(kind === 'batch' ? 'batch' : 'formulation', e).filter(function (p) { return p && p.id; });
+  if (!params.length) return '[]';
+  var comp = _tpEffectiveComposition(kind === 'batch' ? 'batch' : 'formulation', e);
+  var rows = _tpBuildRows(comp.rows);
+  var res = _tpEvaluateAll(params, rows);
+  return JSON.stringify(params.map(function (p) {
+    var r = res[p.id] || {};
+    var v = (!r.error && Number.isFinite(r.value)) ? r.value : null;
+    var warning = null;
+    try { var m = _tpMissingNote(_tpMissingInputs(p.formula, rows)); if (m) warning = m.text; } catch (_) {}
+    var spec = (p.spec && (p.spec.min != null || p.spec.max != null)) ? { min: p.spec.min != null ? p.spec.min : null, max: p.spec.max != null ? p.spec.max : null } : null;
+    var pass = (v != null && spec) ? ((spec.min == null || v >= spec.min) && (spec.max == null || v <= spec.max)) : null;
+    return { name: p.name || '', value: v, unit: p.unit || '', formula: p.formula || '', error: r.error || null,
+      warning: warning, spec: spec, pass: pass, pinned: !!p.pinned, basis: comp.source };
+  }));
+}`;
+
+const _contexts = new WeakMap();   // store db object → its vm context
+function contextFor(db) {
+  let ctx = _contexts.get(db);
+  if (ctx) return ctx;
+  const data = JSON.stringify({
+    ingredients: db.ingredients || [], formulations: db.formulations || [], batches: db.batches || [],
+    settings: db.settings || {},
+  });
+  // A prototype-less sandbox: the classic vm escape (this.constructor.constructor
+  // → the host's Function) has no constructor to walk to.
+  const sandbox = Object.create(null);
+  sandbox.__dbJson = data;
+  ctx = vm.createContext(sandbox);
+  vm.runInContext('var console = { log: function () {}, warn: function () {}, error: function () {}, info: function () {} };'
+    + 'var db = JSON.parse(__dbJson); delete globalThis.__dbJson;\n' + source() + EPILOGUE, ctx, { filename: 'formlab-theoretical.js', timeout: 10000 });
+  _contexts.set(db, ctx);
+  return ctx;
+}
+
+// [{ name, value, unit, formula, error, warning, spec, pass, pinned, basis }] —
+// value null when it can't be computed (error says why); warning is the Params
+// tab's ⚠ note ("2 ingredients missing carb", "sugar in mixed units (…)");
+// basis is 'proposal' (the formula's recipe) or 'actual' (a batch as made).
+export function theoreticalParams(db, kind, id) {
+  try {
+    const ctx = contextFor(db);
+    vm.runInContext('var __id = ' + JSON.stringify(String(id)) + ', __kind = ' + JSON.stringify(kind === 'batch' ? 'batch' : 'formulation') + ';', ctx);
+    return JSON.parse(vm.runInContext('__theo(__kind, __id)', ctx, { timeout: 2000 }));
+  } catch (e) {
+    return [{ name: '(theoretical parameters)', value: null, unit: '', formula: '', error: 'could not compute: ' + ((e && e.message) || e), warning: null, spec: null, pass: null, pinned: false, basis: null }];
+  }
+}

package/tools/formulations.js

@@ -7,6 +7,7 @@
 // ============================================================
 
 import { getStore, resolveById, flattenComposition } from '../data.js';
+import { theoreticalParams } from '../theoretical.js';
 
 // Strip db-internal noise (createdAt, updatedAt) for cleaner LLM output
 // while keeping the human-facing fields the user cares about.
@@ -82,7 +83,7 @@ const list_formulations = {
 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, any recorded process-factor values (cure temp, mix time, RPM, pH — DOE inputs), and recent batches. Accepts either internal id or UID (e.g. FORM-001).',
+    description: 'Get full details for a single formulation including its composition (raw rows AND flattened wt-% leaves with sub-formulas expanded), step procedure, any recorded process-factor values (cure temp, mix time, RPM, pH — DOE inputs), and recent batches. Accepts either internal id or UID (e.g. FORM-001). Also returns `theoreticalParameters`: values computed from the composition the way the app Params tab does (e.g. Energy kcal/100g, NV %, Cost/kg) — each with name, value, unit, formula, spec + pass, and `warning` when ingredients lack a value the formula reads or carry mixed units (those rows are not counted). Quote these; do not recompute nutrition or NV yourself.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -131,6 +132,8 @@ const get_formulation = {
       // Process-factor values (DOE Matrix "+ Factor" columns) — recorded process
       // conditions (cure temp, mix time, RPM, pH, …) treated as DOE INPUTS.
       processFactors: (f.factorValues || []).filter(x => x && x.name).map(x => ({ name: x.name, value: x.value != null ? x.value : '', unit: x.unit || '' })),
+      // Computed by the app's own engine (mcp/theoretical.js → mcp/vendor/).
+      theoreticalParameters: theoreticalParams(db, 'formulation', f.id),
       batchCount: batches.length,
       sampleCount: samples.length,
     };

package/tools/ingredients.js

@@ -170,7 +170,7 @@ const list_ingredients = {
 const get_ingredient = {
   definition: {
     name: 'get_ingredient',
-    description: 'Get full details for a single ingredient: cost ($/kg), GHS safety (pictograms / H- / P-codes / signal word), per-jurisdiction regulatory status, approved sources (the suppliers/manufacturers qualified to supply this material — ASL/AML), inventory lots (balances + expiry + the source each was received from), recent stock movements, and the formulations using it. Accepts internal id or UID (e.g. ING-001).',
+    description: 'Get full details for a single ingredient: cost ($/kg), GHS safety (pictograms / H- / P-codes / signal word), per-jurisdiction regulatory status, approved sources (the suppliers/manufacturers qualified to supply this material — ASL/AML), inventory lots (balances + expiry + the source each was received from), recent stock movements, and the formulations using it, plus its `customFields` (name, value, unit — e.g. protein / carb / fat in g/100g, solids %; what theoretical parameters read). Accepts internal id or UID (e.g. ING-001).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -224,6 +224,10 @@ const get_ingredient = {
       description: ing.description || '',
       notes: ing.notes || '',
       attributes: ing.attributes || {},
+      // User-defined fields: what theoretical parameters read as ing.<name>
+      // (protein / carb / fat in g/100g for nutrition, solids % for NV, …).
+      // The unit is a label; a 0 is a value.
+      customFields: (ing.customFields || []).filter(c => c && c.name).map(c => ({ name: c.name, value: c.value != null ? c.value : '', unit: c.unit || '', ...(c.info ? { info: c.info } : {}) })),
       safety,
       regulatory,
       lots,

package/tools/lab.js

@@ -7,6 +7,7 @@
 // ============================================================
 
 import { getStore, resolveById } from '../data.js';
+import { theoreticalParams } from '../theoretical.js';
 
 // --- Self-contained unit conversion + actual-volume derivation ---------------
 // The MCP server has no access to the app's cost.js helpers, so a small local
@@ -247,7 +248,7 @@ const list_batches = {
 const get_batch = {
   definition: {
     name: 'get_batch',
-    description: 'Get full details for a single batch including its actual composition (as-prepared, when logged), child samples, lineage (parent / sub-blend parents), and — treating the batch as a finished-goods lot — its storage `location` and finished-goods `stockLedger` (shipments out + adjustments; on-hand = produced − sample pulls − sub-batch draws + Σ ledger). Plus finished-product density + actual volume (measured directly or derived as actual mass ÷ measured density — never summed from per-ingredient volumes). Accepts internal id or UID.',
+    description: 'Get full details for a single batch including its actual composition (as-prepared, when logged), child samples, lineage (parent / sub-blend parents), and — treating the batch as a finished-goods lot — its storage `location` and finished-goods `stockLedger` (shipments out + adjustments; on-hand = produced − sample pulls − sub-batch draws + Σ ledger). Plus finished-product density + actual volume (measured directly or derived as actual mass ÷ measured density — never summed from per-ingredient volumes). Accepts internal id or UID. Also returns `theoreticalParameters` computed on the batch as made (its actual composition when logged — `basis: "actual"` — else the recipe of its formula), with the batch parameter list when it overrides the one on the formula; same fields as get_formulation.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -295,6 +296,7 @@ const get_batch = {
         date: e.ts || null, delta: e.delta ?? null, unit: e.unit || b.unit || '', kind: e.kind || '', note: e.note || '',
       })),
       shippedQty: (Array.isArray(b.stockLedger) ? b.stockLedger : []).reduce((s, e) => e.kind === 'shipment' ? s + Math.abs(parseFloat(e.delta) || 0) : s, 0),
+      theoreticalParameters: theoreticalParams(getStore().db, 'batch', b.id),
     };
   },
 };

package/vendor/README.md

@@ -0,0 +1,18 @@
+# Vendored app files — do not edit here
+
+Exact copies of the FormLab app's theoretical-parameter engine, so the MCP
+server computes the same numbers the Params tab shows (the npm package can't
+reach files outside `mcp/`):
+
+| Copy | Source |
+|---|---|
+| `cost.js` | `js/cost.js` |
+| `nesting.js` | `js/nesting.js` |
+| `theoretical-params.js` | `js/views/theoretical-params.js` |
+
+Edit the source, then copy it over:
+
+    cp js/cost.js js/nesting.js js/views/theoretical-params.js mcp/vendor/
+
+The pre-commit hook (`scripts/hooks/pre-commit`) refreshes them when a commit touches a source; `test/mcp-theoretical.test.js` fails while a copy differs. `mcp/theoretical.js`
+runs them in a `node:vm` context holding only a JSON copy of the data.