formlab-mcp 0.6.56 → 0.6.57

package/README.md

@@ -1,14 +1,14 @@
 # formlab-mcp
 
 [![npm](https://img.shields.io/npm/v/formlab-mcp.svg)](https://www.npmjs.com/package/formlab-mcp)
-[![license](https://img.shields.io/npm/l/formlab-mcp.svg)](https://github.com/juliu1980/FormLab/blob/main/LICENSE)
+[![license](https://img.shields.io/npm/l/formlab-mcp.svg)](https://www.npmjs.com/package/formlab-mcp)
 [![FormLab](https://img.shields.io/badge/site-formvix.com-2563eb.svg)](https://formvix.com)
 
-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 reports — **without your data ever leaving your machine**.
+A **read-only Model Context Protocol server** for [FormLab](https://formvix.com). Lets Claude (or any MCP-compatible AI assistant) read and analyze your FormLab data: formulations, ingredients, batches, samples and test reports, from a local export file or your live cloud workspace.
 
-> Local-first + AI-native. Your proprietary recipes stay on your laptop; only the LLM's answer to your question travels.
+> In file mode the server makes no network calls of its own. What a tool returns goes to the model your MCP client uses (for Claude Desktop, Anthropic), so only connect data you're comfortable sending to that provider. See [Privacy and data flow](#privacy-and-data-flow).
 
-Listed in the official MCP Registry as `io.github.juliu1980/formlab-mcp`.
+Listed in the official MCP Registry as `io.github.juliu1980/formlab-mcp`. The source ships in the npm package (MIT).
 
 ## What it does
 
@@ -82,24 +82,34 @@ npm install -g formlab-mcp
 formlab-mcp /path/to/formlab-export.json
 ```
 
-For local development from this repo:
+To read or run the source, unpack it from npm (it ships in the package, MIT):
 
 ```bash
-cd mcp
-npm install
+npm pack formlab-mcp && tar xzf formlab-mcp-*.tgz
+cd package && npm install
 node index.js /path/to/formlab-export.json
 ```
 
 Requires **Node 18+**.
 
+## Try it with sample data
+
+No FormLab account needed: a sample export (the app's Showcase demo) is published on formvix.com.
+
+```bash
+curl -O https://formvix.com/downloads/formlab-demo-export.json
+npx formlab-mcp ./formlab-demo-export.json
+```
+
+Point your MCP client at that file the same way as your own export (see below).
+
 ## 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
+2. **Settings → Data → Export JSON**. This saves `formlab-export-YYYY-MM-DD.json` to your downloads folder.
+3. 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.
+The MCP server watches the file: re-export from FormLab and the next tool call sees the fresh data without restarting the server.
 
 ## Or: LIVE cloud mode (no export needed)
 
@@ -138,7 +148,7 @@ Add this to your `claude_desktop_config.json` (on macOS: `~/Library/Application
 }
 ```
 
-Or for local-dev (from the repo):
+Or from the unpacked package:
 
 ```json
 {
@@ -146,7 +156,7 @@ Or for local-dev (from the repo):
     "formlab": {
       "command": "node",
       "args": [
-        "/Users/you/formlab/mcp/index.js",
+        "/Users/you/package/index.js",
         "/Users/you/Downloads/formlab-export-2026-05-30.json"
       ]
     }
@@ -154,7 +164,7 @@ Or for local-dev (from the repo):
 }
 ```
 
-Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 40 tools become callable in any conversation.
+Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 41 tools become callable in any conversation.
 
 ## Wire it up to Claude Code
 
@@ -169,12 +179,22 @@ export FORMLAB_EXPORT=/Users/you/Downloads/formlab-export-2026-05-30.json
 claude mcp add formlab npx formlab-mcp
 ```
 
-## Privacy and architecture
+## Privacy and data flow
+
+**In both modes, what a tool returns goes to your model.** The server answers your MCP client over stdio, and the client sends tool results (your formulations, test data and so on) to the model it uses: for Claude Desktop, Anthropic. Only connect data you're comfortable sending to that provider.
 
-- **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.)
+**File mode** (an export file):
+
+- **No network calls of its own.** The server reads the export from your disk and talks to your MCP client over stdio. It does not upload the file anywhere.
+- **Hot-reload on file change.** Re-export from FormLab while the server is running and the next tool call picks up fresh data.
+
+**Cloud mode** (`FORMLAB_MCP_TOKEN` set):
+
+- The server sends your token to FormLab's `mcp-data` Edge Function and receives your workspace in return, re-read every 60 seconds (`FORMLAB_REFRESH_SECONDS`).
+- The function reads through a dedicated `mcp_readonly` Postgres role with `SELECT`-only grants, and row-level security limits it to the workspace the token was made for.
+- FormLab stores only a SHA-256 hash of the token. It holds no account session and you can revoke it at any time.
+
+**Read-only, in both modes.** No tool can change your FormLab data.
 
 ## Data shape
 
@@ -185,12 +205,6 @@ The server accepts both FormLab export shapes:
 
 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/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 40 tools (see ./tools/) over stdio. The MCP host (Claude
+// Exposes 41 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.
@@ -72,7 +72,7 @@ if (CLOUD) {
       'Usage: formlab-mcp <path-to-export.json>   (file mode)',
       '   or: set FORMLAB_MCP_TOKEN               (LIVE cloud mode)',
       '',
-      'File mode: export via Settings → Import / Export → Export.',
+      'File mode: export via Settings → Data → Export JSON.',
       'Cloud mode: mint a read-only token in FormLab → Settings → Account →',
       '            AI tools (MCP) → Connect, and set it as FORMLAB_MCP_TOKEN.',
       '',

package/package.json

@@ -1,13 +1,26 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.56",
+  "version": "0.6.57",
   "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.",
+  "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.",
+  "homepage": "https://formvix.com/mcp",
   "type": "module",
   "bin": {
     "formlab-mcp": "./index.js"
   },
   "main": "index.js",
+  "files": [
+    "index.js",
+    "data.js",
+    "cloud.js",
+    "calibration.js",
+    "peptide.js",
+    "theoretical.js",
+    "tools/",
+    "vendor/",
+    "server.json",
+    "README.md"
+  ],
   "scripts": {
     "start": "node index.js",
     "dev": "node --watch index.js"
@@ -32,10 +45,5 @@
     "design-of-experiments",
     "claude"
   ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/juliu1980/FormLab",
-    "directory": "mcp"
-  }
+  "license": "MIT"
 }

package/server.json

@@ -1,19 +1,14 @@
 {
   "$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.56",
+  "description": "Read-only MCP server for FormLab formulation data: a local export file or your live cloud workspace.",
+  "version": "0.6.57",
   "websiteUrl": "https://formvix.com/mcp",
-  "repository": {
-    "url": "https://github.com/juliu1980/FormLab",
-    "source": "github",
-    "subfolder": "mcp"
-  },
   "packages": [
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.6.56",
+      "version": "0.6.57",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"
@@ -22,7 +17,7 @@
         {
           "type": "positional",
           "name": "exportPath",
-          "description": "File mode: absolute path to a FormLab export JSON (Data → Export JSON). Omit when using cloud mode (set FORMLAB_MCP_TOKEN instead).",
+          "description": "File mode: absolute path to a FormLab export JSON (Settings → Data → Export JSON). Omit when using cloud mode (set FORMLAB_MCP_TOKEN instead).",
           "isRequired": false,
           "format": "filepath",
           "value": "/path/to/formlab-export.json"

package/vendor/cost.js

@@ -1867,7 +1867,7 @@ function _weighoutDensityLineHtml(w) {
     let src = d.how === 'measured' ? 'measured' : (d.how === 'spec' ? 'from spec' : 'entered');
     if (d.batchId && typeof db !== 'undefined') {
       const b = (db.batches || []).find(x => x.id === d.batchId);
-      if (b) src += ` on <a href="#" onclick="navigate('batch-detail','${esc(b.id)}');return false" style="color:var(--dk-blue-fg, #2563eb)">${esc(b.uid)}</a>`;
+      if (b) src += ` on <a href="#" onclick="navigate('batch-detail','${escJsAttr(b.id)}');return false" style="color:var(--dk-blue-fg, #2563eb)">${esc(b.uid)}</a>`;
     }
     const parts = (w.partsSum != null && isFinite(w.partsSum) && Math.abs(w.partsSum - w.qty) > 1e-6)
       ? ` Pure-ingredient volumes sum to ${+w.partsSum.toFixed(2)} ${esc(w.unit)} — volumes aren't additive on mixing; the masses are what to weigh.` : '';

package/SUBMISSION.md

@@ -1,132 +0,0 @@
-# MCP submission — ready-to-paste materials
-
-Both directory paths are prepped. Path B is fastest; Path A is the canonical
-registry placement. Recommended order: B first (immediate discoverability),
-then A (long-term legitimacy).
-
----
-
-## Path B — `awesome-mcp-servers` PR
-
-Three lists worth submitting to, in rough order of reach:
-
-1. **[punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)** (~50k stars, primary)
-2. **[appcypher/awesome-mcp-servers](https://github.com/appcypher/awesome-mcp-servers)**
-3. **[wong2/awesome-mcp-servers](https://github.com/wong2/awesome-mcp-servers)**
-
-### Entry markdown (drop into the right category section)
-
-```markdown
-- [**formlab-mcp**](https://github.com/juliu1980/FormLab/tree/main/mcp) - Local-first read access to your [FormLab](https://formvix.com) lab notebook — formulations, ingredients, batches, samples, test results, DOE matrices. Data stays on your machine; only the LLM's answer travels. [Listed in the official MCP Registry.](https://registry.modelcontextprotocol.io/?search=formlab) [![npm](https://img.shields.io/npm/v/formlab-mcp.svg)](https://www.npmjs.com/package/formlab-mcp)
-```
-
-### Suggested category
-
-Best fit on `punkpeye/awesome-mcp-servers`: **"📊 Data Science Tools"** or
-**"🔬 Knowledge & Memory"** depending on how the list is structured. Skim the
-TOC and pick whichever section already has domain-specific lab/research
-servers. If neither fits, **"🛠️ Other Tools and Integrations"** is the safe
-catch-all.
-
-### PR title
-
-```
-Add formlab-mcp — local-first lab-notebook server for chem/cosmetic R&D
-```
-
-### PR body
-
-```markdown
-Adds **formlab-mcp**, a read-only MCP server that exposes a [FormLab](https://formvix.com)
-lab notebook export to Claude (or any MCP client). FormLab is a browser-based
-local-first ELN for formulation R&D — paints, coatings, cosmetics, polymers.
-
-The server lets users ask Claude things like _"which of my formulations use
-silicone fluid at 5%+?"_, _"compare FORM-001 and FORM-004 side by side"_,
-_"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.
-
-**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.
-
-- Repo: https://github.com/juliu1980/FormLab/tree/main/mcp
-- npm: https://www.npmjs.com/package/formlab-mcp
-- Listed in the official MCP Registry: `io.github.juliu1980/formlab-mcp`
-- Node 18+; runs via `npx formlab-mcp /path/to/export.json`
-- License: MIT
-
-Happy to move the entry to a different category if there's a better fit.
-```
-
-### Submission workflow
-
-For each fork target above:
-
-1. Visit https://github.com/punkpeye/awesome-mcp-servers (or the alt)
-2. Open `README.md` → click ✏ (Edit) → GitHub will fork on your behalf
-3. Find the appropriate `###` category section
-4. Paste the **Entry markdown** in alphabetical order within the section
-5. Commit message: `Add formlab-mcp`
-6. Open PR with the **PR title** and **PR body** above
-
-Total time for all three: ~15 minutes.
-
----
-
-## Path A — Official MCP Registry
-
-This places `formlab-mcp` in `https://registry.modelcontextprotocol.io`,
-which is what future MCP-aware tools will query first.
-
-### Prereqs
-
-```bash
-# Go 1.24+ — needed to build mcp-publisher
-brew install go
-
-# Build the publisher CLI
-git clone https://github.com/modelcontextprotocol/registry
-cd registry
-make publisher          # produces ./bin/mcp-publisher
-sudo mv bin/mcp-publisher /usr/local/bin/  # or add to PATH
-```
-
-### Manifest
-
-Already written to `mcp/server.json` in this repo. Uses:
-- Namespace: `io.github.juliu1980/formlab-mcp` (GitHub OAuth proves ownership)
-- Status: `active`
-- Repository: `https://github.com/juliu1980/FormLab` with subfolder `mcp`
-- Version: pulled from `package.json` (currently `0.6.12`)
-- Package: npm `formlab-mcp` with stdio transport + positional `exportPath` arg
-
-### Publish (the OAuth step is interactive)
-
-```bash
-cd ~/GitHub/formlab/mcp
-mcp-publisher login        # opens GitHub OAuth in your browser as juliu1980
-mcp-publisher publish      # reads server.json and submits
-```
-
-### Verify
-
-After publish, the server appears at:
-- `https://registry.modelcontextprotocol.io/v0/servers?search=formlab`
-
-### Versioning future updates
-
-Bump `package.json` `version` AND `mcp/server.json`'s `version` + the package
-version, then re-run `mcp-publisher publish`. The CLI rejects duplicate
-version submissions.
-
----
-
-## After both paths land
-
-- Post to X / LinkedIn announcing it (memory file has a draft)
-- Cross-post to r/cosmeticchemistry, r/paint, r/Chemistry — any lab-adjacent
-  subreddits where local-first + AI lands well
-- Add a section to the formvix.com landing page linking to the registry entry

package/supabase/.temp/linked-project.json

@@ -1 +0,0 @@
-{"ref":"ufizhypibwqqpavhxdwt","name":"FormLab","organization_id":"pbplgvokbayhflgrvygl","organization_slug":"pbplgvokbayhflgrvygl"}