formlab-mcp 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# formlab-mcp
+
+A **read-only Model Context Protocol server** for [FormLab](https://formvix.com). Lets Claude (or any MCP-compatible AI assistant) read and analyze your local FormLab database — your formulations, ingredients, batches, samples and test results — **without your data ever leaving your machine**.
+
+> Local-first + AI-native. Your proprietary recipes stay on your laptop; only the LLM's answer to your question travels.
+
+## What it does
+
+Ask Claude (or another MCP client) things like:
+
+- _"Which of my formulations use silicone fluid at 5% or more?"_
+- _"Compare the composition of Formula FORM-001 and FORM-004 side by side."_
+- _"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?"_
+
+## Tools exposed
+
+| Tool | Purpose |
+|---|---|
+| `list_formulations` | Filtered list of recipes |
+| `get_formulation` | Full record + flattened wt-% composition (sub-formulas expanded) |
+| `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 |
+| `get_ingredient` | Full record + supplier / stock / formulations using it |
+| `list_batches` | Filtered list of production / lab-prep events |
+| `get_batch` | Full record + actual composition + samples + blend lineage |
+| `list_samples` | Filtered list of physical specimens |
+| `get_sample` | Full record + canonical variant + test results + blend lineage |
+| `list_test_results` | Filtered list of test reports |
+| `get_test_result` | Full record + every measurement value |
+| `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 |
+
+## Install
+
+```bash
+# From npm (once published):
+npm install -g formlab-mcp
+
+# Or run directly without installing:
+npx formlab-mcp /path/to/formlab-export.json
+```
+
+For local development from this repo:
+
+```bash
+cd mcp
+npm install
+node index.js /path/to/formlab-export.json
+```
+
+Requires **Node 18+**.
+
+## Get your FormLab export
+
+1. Open FormLab
+2. Sidebar → **⇅ Import / Export**
+3. Click **Export** — saves `formlab-export-YYYY-MM-DD.json` to your downloads folder
+4. Point this MCP at the downloaded file
+
+The MCP server watches the file — re-export from FormLab and the next tool call sees the fresh data without restarting the server.
+
+## Wire it up to Claude Desktop
+
+Add this to your `claude_desktop_config.json` (on macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "formlab": {
+      "command": "npx",
+      "args": ["formlab-mcp", "/Users/you/Downloads/formlab-export-2026-05-30.json"]
+    }
+  }
+}
+```
+
+Or for local-dev (from the repo):
+
+```json
+{
+  "mcpServers": {
+    "formlab": {
+      "command": "node",
+      "args": [
+        "/Users/you/Documents/GitHub/formlab/mcp/index.js",
+        "/Users/you/Downloads/formlab-export-2026-05-30.json"
+      ]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 15 tools become callable in any conversation.
+
+## Wire it up to Claude Code
+
+```bash
+claude mcp add formlab npx formlab-mcp /Users/you/Downloads/formlab-export.json
+```
+
+Or with a stored env var:
+
+```bash
+export FORMLAB_EXPORT=/Users/you/Downloads/formlab-export-2026-05-30.json
+claude mcp add formlab npx formlab-mcp
+```
+
+## Privacy and architecture
+
+- **No network calls.** The server runs on stdio between Claude and your local Node process. Your data file never leaves your disk.
+- **No FormLab cloud.** FormLab itself is a local-first app; the MCP follows the same model.
+- **Hot-reload on file change.** Re-export from FormLab while the server is running — the next tool call picks up fresh data.
+- **Read-only.** Tier 1 cannot mutate your FormLab data. (Write tools are planned for a future paid "Pro" tier — register / batch / log-test mutations with cascade-safe confirmation.)
+
+## Data shape
+
+The server accepts both FormLab export shapes:
+
+- **Wrapped FAIR export**: `{ "fair": {...metadata...}, "data": {...db...} }`
+- **Legacy bare-db JSON**: `{...db...}` directly
+
+The wrapped form is the default since 2026; the legacy form is supported for older exports.
+
+## Tier 2 (planned, paid)
+
+Live file-sync with write tools: `create_formulation`, `update_formulation`, `log_test_result`, `create_batch`, etc. Mutations from Claude write back to the same JSON FormLab reads. Conflict detection, cascade-safe deletes, schema versioning.
+
+Not yet shipped — see the FormLab roadmap.
+
+## License
+
+MIT

package/data.js

@@ -0,0 +1,163 @@
+// ============================================================
+// DATA LOADER — accepts both FormLab export shapes
+//   1. Wrapped FAIR export:  { fair: {...}, data: {...db...} }
+//   2. Legacy bare-db JSON:  {...db...} directly
+// And exposes a single normalized "store" object plus helpers
+// for the tools to query against.
+// ============================================================
+
+import { readFileSync, watch } from 'node:fs';
+import { resolve } from 'node:path';
+
+// Module-level mutable store — re-assigned on hot-reload when the
+// watched file changes. Tools read from getStore() to always see
+// the latest data without holding a stale reference.
+let _store = null;
+let _path  = null;
+
+export function loadStore(filePath) {
+  _path = resolve(filePath);
+  const raw = readFileSync(_path, 'utf8');
+  const parsed = JSON.parse(raw);
+  // Detect wrapped vs legacy shape. A wrapped export has top-level
+  // `fair` metadata + `data` payload. Legacy is just the db object
+  // with ingredients/formulations/etc. at the root.
+  const db = (parsed && typeof parsed === 'object' && parsed.fair && parsed.data)
+    ? parsed.data
+    : parsed;
+  const meta = (parsed && parsed.fair) || null;
+  _store = {
+    db,
+    meta,
+    loadedAt: new Date().toISOString(),
+    sourcePath: _path,
+    // Pre-compute commonly-used indexes for O(1) lookups instead
+    // of repeated linear scans across every tool call.
+    indexes: _buildIndexes(db),
+  };
+  return _store;
+}
+
+export function getStore() {
+  if (!_store) throw new Error('Data store not loaded. Call loadStore(path) first.');
+  return _store;
+}
+
+// Re-read the file on disk-change. Useful when the user re-exports
+// FormLab while the MCP server is running — the next tool call sees
+// fresh data without restarting the server.
+export function watchStore(onReload) {
+  if (!_path) throw new Error('Cannot watch — no path loaded.');
+  let timer = null;
+  watch(_path, (eventType) => {
+    if (eventType !== 'change') return;
+    // Debounce: editors often fire multiple change events per save
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      try {
+        loadStore(_path);
+        if (onReload) onReload(_store);
+      } catch (e) {
+        // Don't crash the server on a malformed re-export — keep the
+        // previous good state in memory and surface the error on the
+        // next tool call.
+        console.error('[formlab-mcp] reload failed:', e.message);
+      }
+    }, 150);
+  });
+}
+
+function _buildIndexes(db) {
+  const byId = (arr) => {
+    const m = new Map();
+    (arr || []).forEach(x => { if (x && x.id) m.set(x.id, x); });
+    return m;
+  };
+  return {
+    formulationsById: byId(db.formulations),
+    ingredientsById:  byId(db.ingredients),
+    batchesById:      byId(db.batches),
+    samplesById:      byId(db.samples),
+    testResultsById:  byId(db.testResults),
+    projectsById:     byId(db.projects),
+    templatesById:    byId(db.templates),
+    parametersById:   byId(db.parameters),
+    equipmentById:    byId(db.equipment),
+  };
+}
+
+// ============================================================
+// Shared helpers used across tools
+// ============================================================
+
+// Resolve a record by either UID (FORM-001) or internal id. Lets
+// users reference entities by the human-readable UID they see in
+// FormLab without having to dig out the opaque internal id.
+export function resolveById(collection, idOrUid) {
+  const db = getStore().db;
+  const arr = db[collection] || [];
+  if (!idOrUid) return null;
+  return arr.find(x => x && (x.id === idOrUid || x.uid === idOrUid)) || null;
+}
+
+// Flatten a formulation's composition into leaf ingredient wt-%.
+// Walks sub-formula rows recursively (cap depth to break cycles).
+// Mirrors the algorithm in FormLab's js/nesting.js _flattenComposition.
+export function flattenComposition(formulation, depth = 0) {
+  const MAX_DEPTH = 5;
+  if (!formulation || !Array.isArray(formulation.composition) || depth > MAX_DEPTH) {
+    return { rows: [] };
+  }
+  const { db } = getStore();
+  const rows = [];
+  const allPct = formulation.composition.every(c => {
+    const u = String(c.unit || 'wt%').trim().toLowerCase();
+    return u.startsWith('wt') || u === '%';
+  });
+  // Total mass denominator for renormalization when sub-formulas are present
+  let totalWeight = 0;
+  formulation.composition.forEach(c => {
+    if (!c) return;
+    const amt = parseFloat(c.amount);
+    if (!isFinite(amt)) return;
+    totalWeight += amt;
+  });
+  if (totalWeight <= 0) return { rows };
+
+  formulation.composition.forEach(c => {
+    if (!c) return;
+    const amt = parseFloat(c.amount);
+    if (!isFinite(amt)) return;
+    const fraction = amt / totalWeight;
+    if (c.formulationId) {
+      const sub = db.formulations.find(g => g.id === c.formulationId);
+      if (!sub) return;
+      const sub_flat = flattenComposition(sub, depth + 1);
+      sub_flat.rows.forEach(r => {
+        rows.push({
+          ingredientId: r.ingredientId,
+          ingredientName: r.ingredientName,
+          weightFraction: r.weightFraction * fraction,
+          role: r.role || c.role || '',
+        });
+      });
+    } else if (c.ingredientId) {
+      const ing = db.ingredients.find(i => i.id === c.ingredientId);
+      rows.push({
+        ingredientId: c.ingredientId,
+        ingredientName: ing?.name || c.ingredientId,
+        weightFraction: allPct ? amt / 100 : fraction,
+        role: c.role || '',
+      });
+    }
+  });
+  // Coalesce duplicate leaves (same ingredient reachable via multiple
+  // sub-formulas) by summing their weight fractions.
+  const merged = new Map();
+  rows.forEach(r => {
+    const prev = merged.get(r.ingredientId);
+    if (prev) prev.weightFraction += r.weightFraction;
+    else merged.set(r.ingredientId, { ...r });
+  });
+  return { rows: [...merged.values()] };
+}

package/index.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// ============================================================
+// FormLab MCP server — read-only entry point.
+//
+// Usage:
+//   node index.js /path/to/formlab-export-2026-05-30.json
+//   FORMLAB_EXPORT=/path/to/export.json node index.js
+//   formlab-mcp /path/to/export.json   (when installed via npm)
+//
+// Exposes 13 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.
+//
+// Hot-reload: if the export file changes on disk while the server
+// is running, the store is re-read automatically so the next tool
+// call sees fresh data. No restart needed.
+// ============================================================
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { loadStore, watchStore, getStore } from './data.js';
+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';
+
+const filePath = process.argv[2] || process.env.FORMLAB_EXPORT;
+if (!filePath) {
+  process.stderr.write([
+    'Usage: formlab-mcp <path-to-export.json>',
+    'Or set FORMLAB_EXPORT=<path> and call without args.',
+    '',
+    'Export your FormLab database via Settings → Import / Export → Export,',
+    'then point this server at the downloaded formlab-export-YYYY-MM-DD.json.',
+    '',
+  ].join('\n'));
+  process.exit(1);
+}
+
+try {
+  loadStore(filePath);
+} catch (e) {
+  process.stderr.write(`[formlab-mcp] failed to load export: ${e.message}\n`);
+  process.exit(1);
+}
+
+const store = getStore();
+process.stderr.write([
+  `[formlab-mcp] loaded ${store.sourcePath}`,
+  store.meta
+    ? `  schema=${store.meta.schemaName} v${store.meta.schemaVersion} exportedAt=${store.meta.exportedAt}`
+    : `  (legacy bare-db shape — no FAIR metadata)`,
+  `  records: ${
+    [
+      `${(store.db.ingredients  || []).length} ingredients`,
+      `${(store.db.formulations || []).length} formulas`,
+      `${(store.db.batches      || []).length} batches`,
+      `${(store.db.samples      || []).length} samples`,
+      `${(store.db.testResults  || []).length} test results`,
+    ].join(' · ')
+  }`,
+  '',
+].join('\n'));
+
+watchStore((s) => {
+  process.stderr.write(`[formlab-mcp] reloaded — ${(s.db.formulations||[]).length} formulas now\n`);
+});
+
+// All tools live in tools/*.js as a flat { definition, handler } pair.
+// Concatenate the four modules' exports into a single registry the
+// MCP server can use for both list_tools and call_tool dispatch.
+const TOOLS = [
+  ...Object.values(formulations.tools),
+  ...Object.values(ingredients.tools),
+  ...Object.values(lab.tools),
+  ...Object.values(analytics.tools),
+];
+
+const server = new Server(
+  { name: 'formlab-mcp', version: '0.1.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(t => t.definition),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  const tool = TOOLS.find(t => t.definition.name === name);
+  if (!tool) {
+    return {
+      content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+      isError: true,
+    };
+  }
+  try {
+    const result = await tool.handler(args || {});
+    // All tool handlers return either a plain object/array (auto-
+    // serialized as JSON text) or a pre-formatted string. The MCP
+    // protocol wants content as { type: 'text', text: '...' }.
+    const text = typeof result === 'string'
+      ? result
+      : JSON.stringify(result, null, 2);
+    return { content: [{ type: 'text', text }] };
+  } catch (e) {
+    return {
+      content: [{ type: 'text', text: `Error: ${e.message}` }],
+      isError: true,
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write('[formlab-mcp] ready — listening on stdio\n');

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "formlab-mcp",
+  "version": "0.1.0",
+  "description": "Read-only Model Context Protocol server for FormLab — lets Claude (and other MCP clients) read and analyze your local FormLab export. Your recipes never leave your machine.",
+  "type": "module",
+  "bin": {
+    "formlab-mcp": "./index.js"
+  },
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "dev": "node --watch index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "formlab",
+    "chemistry",
+    "formulation",
+    "lab-notebook",
+    "doe",
+    "design-of-experiments",
+    "claude"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/juliu1980/FormLab",
+    "directory": "mcp"
+  }
+}