formlab-mcp 0.6.15 → 0.6.17

package/README.md

@@ -47,6 +47,7 @@ Ask Claude (or another MCP client) things like:
 | `get_coverage_matrix` | Which formulations × parameters have been measured (TEST coverage) |
 | `compare_batches` | Reproducibility of 2+ runs (ideally of one formula): each run's **yield %**, actual produced mass, cost/kg; per-ingredient **drift** across the runs vs the formula's proposed wt-%; and the biggest **outlier** run. `basis`: `wt_percent` (default) or `amount` |
 | `get_batch_pivot` | Production analytics — aggregate batches by `group_by` (formula / status / month / prepared_by / project) × `metric` (count, avg_yield_pct, total_produced_kg, avg_cost_per_batch, total_samples, total_tests), with share + total for additive metrics. Optional `batch_uids` scope + `status` filter |
+| `get_project_pivot` | Portfolio analytics — aggregate projects by `group_by` (status / phase / priority / business_unit / site / customer / lead, or `cf:<custom field>`) × `metric` (count, total_formulas / batches / samples, total_cost, avg_formulas / batches / cost_per_batch), rolling child activity + cost up by any project attribute. Optional `project_uids` scope |
 | `get_stability` | Grounded stability / shelf-life analysis for a formulation, sample or batch × parameter (auto-detected): time-series, drift (per-month slope + R²), an I-chart (mean ±3σ + out-of-control points), spec status, and an ICH-Q1E-flavored projected shelf life (point + 95%-CI crossing), split by storage condition |
 | `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` |
@@ -148,7 +149,7 @@ Or for local-dev (from the repo):
 }
 ```
 
-Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 36 tools become callable in any conversation.
+Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 37 tools become callable in any conversation.
 
 ## Wire it up to Claude Code
 

package/SUBMISSION.md

@@ -47,7 +47,7 @@ _"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.
 
-**36 read-only tools** covering formulations, ingredients, batches, samples,
+**37 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.

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 36 tools (see ./tools/) over stdio. The MCP host (Claude
+// Exposes 37 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.

package/package.json

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

package/tools/batch-analyze.js

@@ -10,7 +10,7 @@
 // ============================================================
 
 import { getStore, resolveById, flattenComposition } from '../data.js';
-import { _batchActualMassKg, _massToKg } from './lab.js';
+import { _batchActualMassKg, _massToKg, _batchUnitMassKg } from './lab.js';
 import { _costPerKg } from './ingredients.js';
 
 // ---- shared compute (mirrors _bcActualPctMap / _bcProposedPctMap / _bcSpreadLevel) ----
@@ -43,7 +43,7 @@ function _amountMap(b) {
   return out;
 }
 
-function _targetKg(b) { const q = parseFloat(b.targetQuantity); return isFinite(q) ? _massToKg(q, b.unit) : null; }
+function _targetKg(b) { const q = parseFloat(b.targetQuantity); if (!isFinite(q)) return null; const mk = _massToKg(q, b.unit); if (mk != null) return mk; const umk = _batchUnitMassKg(b); return umk != null ? q * umk : null; }
 function _yieldPct(b) { const tk = _targetKg(b), mk = _batchActualMassKg(b); return (tk && tk > 0 && mk != null) ? +(mk / tk * 100).toFixed(1) : null; }
 
 // Blend cost per kg = Σ ingredient costPerKg × weightFraction over the flattened
@@ -231,4 +231,71 @@ const get_batch_pivot = {
   },
 };
 
-export const tools = { compare_batches, get_batch_pivot };
+// ============================================================
+// get_project_pivot — portfolio analytics (parity with the in-app Projects
+// Portfolio Pivot, js/views/projects-pivot.js). Group the project portfolio by
+// any project attribute and measure count or rolled-up child activity / cost.
+// ============================================================
+const _PROJ_GROUP_LABEL = { status: 'Status', phase: 'Phase', priority: 'Priority', business_unit: 'Business Unit', site: 'Site', customer: 'Customer', lead: 'Lead' };
+const _PROJ_GROUP_FIELD = { status: 'status', phase: 'phase', priority: 'priority', business_unit: 'businessUnit', site: 'site', customer: 'customer', lead: 'lead' };
+const _PROJ_METRIC_LABEL = { count: 'Project count', total_formulas: 'Total formulas', total_batches: 'Total batches', total_samples: 'Total samples', total_cost: 'Total batch cost', avg_formulas: 'Avg formulas / project', avg_batches: 'Avg batches / project', avg_cost_per_batch: 'Avg cost / batch' };
+
+function _projFormsOf(p, db) { return (db.formulations || []).filter(f => f.projectId === p.id); }
+function _projBatchesOf(p, db) { const ids = new Set(_projFormsOf(p, db).map(f => f.id)); return (db.batches || []).filter(b => ids.has(b.formulationId)); }
+function _projSampleCount(p, db) { const ids = new Set(_projFormsOf(p, db).map(f => f.id)); return (db.samples || []).filter(s => ids.has(s.formulationId)).length; }
+function _projBatchCost(p, db) { let sum = 0, count = 0; _projBatchesOf(p, db).forEach(b => { const f = (db.formulations || []).find(x => x.id === b.formulationId) || null; const perKg = _batchCostPerKg(b, f); const mk = _batchActualMassKg(b) || _targetKg(b); if (perKg != null && mk != null && isFinite(perKg * mk)) { sum += perKg * mk; count++; } }); return { sum, count }; }
+function _projGroupKey(p, groupBy) {
+  if (groupBy && groupBy.startsWith('cf:')) { const name = groupBy.slice(3); const cf = (p.customFields || []).find(c => c && c.name === name); return (cf && cf.value) || '(none)'; }
+  const field = _PROJ_GROUP_FIELD[groupBy];
+  return (p[field] || '').trim() || `(no ${(_PROJ_GROUP_LABEL[groupBy] || groupBy).toLowerCase()})`;
+}
+function _projMetricVal(projs, metric, db) {
+  if (metric === 'count') return projs.length;
+  if (metric === 'total_formulas') return projs.reduce((s, p) => s + _projFormsOf(p, db).length, 0);
+  if (metric === 'total_batches') return projs.reduce((s, p) => s + _projBatchesOf(p, db).length, 0);
+  if (metric === 'total_samples') return projs.reduce((s, p) => s + _projSampleCount(p, db), 0);
+  if (metric === 'total_cost') { let sum = 0, count = 0; projs.forEach(p => { const c = _projBatchCost(p, db); sum += c.sum; count += c.count; }); return count ? +sum.toFixed(2) : null; }
+  if (metric === 'avg_cost_per_batch') { let sum = 0, count = 0; projs.forEach(p => { const c = _projBatchCost(p, db); sum += c.sum; count += c.count; }); return count ? +(sum / count).toFixed(2) : null; }
+  if (metric === 'avg_formulas') return projs.length ? +(projs.reduce((s, p) => s + _projFormsOf(p, db).length, 0) / projs.length).toFixed(1) : null;
+  if (metric === 'avg_batches') return projs.length ? +(projs.reduce((s, p) => s + _projBatchesOf(p, db).length, 0) / projs.length).toFixed(1) : null;
+  return 0;
+}
+
+const get_project_pivot = {
+  definition: {
+    name: 'get_project_pivot',
+    description: 'Aggregate the project portfolio by a project attribute (status / phase / priority / business_unit / site / customer / lead, or a custom field via "cf:<name>") and a metric (count, total_formulas, total_batches, total_samples, total_cost, avg_formulas, avg_batches, avg_cost_per_batch). The portfolio-manager view: rolls child formulas/batches/samples/cost up by any project dimension. total_cost = each batch cost/kg × size summed over the group; avg_cost_per_batch is weighted (total ÷ costed batches).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        group_by: { type: 'string', description: 'status | phase | priority | business_unit | site | customer | lead | cf:<custom field name> (default status).' },
+        metric: { type: 'string', enum: ['count', 'total_formulas', 'total_batches', 'total_samples', 'total_cost', 'avg_formulas', 'avg_batches', 'avg_cost_per_batch'], description: 'Metric per group (default count).' },
+        project_uids: { type: 'array', items: { type: 'string' }, description: 'Optional — scope to these projects; omit for all.' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const db = getStore().db;
+    let groupBy = args.group_by || 'status';
+    if (!(_PROJ_GROUP_LABEL[groupBy] || (typeof groupBy === 'string' && groupBy.startsWith('cf:')))) groupBy = 'status';
+    const metric = _PROJ_METRIC_LABEL[args.metric] ? args.metric : 'count';
+    let projects = db.projects || [];
+    let scope = 'all';
+    if (Array.isArray(args.project_uids) && args.project_uids.length) {
+      const ids = new Set(args.project_uids.map(u => { const p = resolveById('projects', u); return p ? p.id : null; }).filter(Boolean));
+      projects = projects.filter(p => ids.has(p.id));
+      scope = 'selected';
+    }
+    const groups = {};
+    projects.forEach(p => { const k = _projGroupKey(p, groupBy); (groups[k] = groups[k] || []).push(p); });
+    const additive = ['count', 'total_formulas', 'total_batches', 'total_samples', 'total_cost'].includes(metric);
+    const rows = Object.entries(groups).map(([key, ps]) => ({ key, projects: ps.length, value: _projMetricVal(ps, metric, db) }))
+      .sort((a, b) => (b.value == null ? -Infinity : b.value) - (a.value == null ? -Infinity : a.value) || a.key.localeCompare(b.key));
+    const total = (additive && rows.some(r => r.value != null)) ? +rows.reduce((s, r) => s + (r.value || 0), 0).toFixed(2) : null;
+    if (additive && total) rows.forEach(r => { r.share_pct = +((r.value || 0) / total * 100).toFixed(1); });
+    const groupByLabel = _PROJ_GROUP_LABEL[groupBy] || (groupBy.startsWith('cf:') ? groupBy.slice(3) : groupBy);
+    return { group_by: groupBy, group_by_label: groupByLabel, metric, metric_label: _PROJ_METRIC_LABEL[metric], scope, project_count: projects.length, additive, total, rows };
+  },
+};
+
+export const tools = { compare_batches, get_batch_pivot, get_project_pivot };

package/tools/lab.js

@@ -18,9 +18,19 @@ const _MASS_TO_KG = { mg: 1e-6, cg: 1e-5, dg: 1e-4, g: 1e-3, hg: 0.1, kg: 1, oz:
 const _VOL_TO_L = { 'µl': 1e-6, ul: 1e-6, ml: 1e-3, cl: 1e-2, dl: 0.1, l: 1, gal: 3.78541, fl_oz: 0.0295735, floz: 0.0295735, pt: 0.473176, qt: 0.946353, tsp: 0.00492892, tbsp: 0.0147868, cup: 0.236588 };
 function _massToKg(v, u) { const f = _MASS_TO_KG[String(u || '').trim().toLowerCase()]; return (f != null && isFinite(v)) ? v * f : null; }
 function _volToL(v, u) { const f = _VOL_TO_L[String(u || '').trim().toLowerCase()]; return (f != null && isFinite(v)) ? v * f : null; }
+// Mass (kg) of one count-unit (tablet/capsule/…) from b.unitMass {value, unit};
+// null when unset. Lets dose-form batches derive a total mass (count × unit mass).
+function _batchUnitMassKg(b) {
+  if (!b || !b.unitMass) return null;
+  const v = parseFloat(b.unitMass.value);
+  return (isFinite(v) && v > 0) ? _massToKg(v, b.unitMass.unit) : null;
+}
 function _batchActualMassKg(b) {
   const y = parseFloat(b.actualYield);
-  if (isFinite(y)) { const kg = _massToKg(y, b.unit); if (kg != null) return kg; }
+  if (isFinite(y)) {
+    const kg = _massToKg(y, b.unit); if (kg != null) return kg;
+    const umk = _batchUnitMassKg(b); if (umk != null) return y * umk;   // count unit × per-unit mass
+  }
   if (Array.isArray(b.actualComposition)) {
     let t = 0, any = false;
     for (const c of b.actualComposition) { const kg = _massToKg(parseFloat(c.amount), c.unit); if (kg != null) { t += kg; any = true; } }
@@ -68,6 +78,9 @@ function _trimBatch(b, formulationsById) {
     status: b.status || '',
     targetQuantity: b.targetQuantity ?? null,
     unit: b.unit || '',
+    // Per-count-unit mass for dose-form batches (tablet/capsule) — lets a count
+    // batch derive a total mass (count × unit mass) for cost / yield.
+    unitMass: (b.unitMass && b.unitMass.value != null) ? { value: b.unitMass.value, unit: b.unitMass.unit || 'mg' } : null,
     actualYield: b.actualYield ?? null,
     // Finished-product density (g/mL === kg/L), measured on the blend, + the
     // derived/measured actual VOLUME (mass is the additive quantity; volume is
@@ -303,4 +316,4 @@ const get_sample = {
 export const tools = { list_batches, get_batch, list_samples, get_sample };
 
 // Exported for the batch-analyze tools so they reuse the SAME mass logic.
-export { _batchActualMassKg, _massToKg };
+export { _batchActualMassKg, _massToKg, _batchUnitMassKg };