formlab-mcp 0.1.4 → 0.1.7

package/README.md

@@ -8,6 +8,8 @@ A **read-only Model Context Protocol server** for [FormLab](https://formvix.com)
 
 > Local-first + AI-native. Your proprietary recipes stay on your laptop; only the LLM's answer to your question travels.
 
+Listed in the official MCP Registry as `io.github.juliu1980/formlab-mcp`.
+
 ## What it does
 
 Ask Claude (or another MCP client) things like:
@@ -17,6 +19,9 @@ Ask Claude (or another MCP client) things like:
 - _"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?"_
+- _"List all peptide ingredients with purity above 95%."_
+- _"Which botanicals do I source from Madagascar?"_
+- _"Find ingredients where the sequence contains KTTKS."_
 
 ## Tools exposed
 
@@ -26,8 +31,8 @@ Ask Claude (or another MCP client) things like:
 | `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_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 / stock / formulations using it. Returns every class-specific sub-object when present: `sequence` (peptide / oligo), `taxon` (NCBI ID + scientific name), `ingredientClass`, `extractDetails`, `sequenceDetails`, `polymerDetails`, `surfactantDetails`, `pigmentDetails`, `fragranceDetails` |
 | `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 |
@@ -37,6 +42,7 @@ Ask Claude (or another MCP client) things like:
 | `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 |
+| `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). |
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formlab-mcp",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "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 local FormLab export. Your recipes never leave your machine.",
   "type": "module",
@@ -18,6 +18,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4"
   },
+  "optionalDependencies": {
+    "@rdkit/rdkit": "^2024.9.1"
+  },
   "keywords": [
     "mcp",
     "model-context-protocol",

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 — talk to your local lab notebook via Claude. Data stays local.",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "websiteUrl": "https://formvix.com",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.1.4",
+      "version": "0.1.7",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tools/ingredients.js

@@ -23,9 +23,15 @@ function _trimIngredient(i) {
     stockUnit: i.stockUnit || null,
     // Tier 1 expansion fields — keep optional so legacy exports stay clean.
     ...(i.ingredientClass ? { ingredientClass: i.ingredientClass } : {}),
+    ...(i.inchiKey ? { inchiKey: i.inchiKey } : {}),
     ...(i.sequence ? { sequence: i.sequence } : {}),
     ...(i.taxon ? { taxon: i.taxon } : {}),
-    ...(i.extractDetails ? { extractDetails: i.extractDetails } : {}),
+    ...(i.extractDetails    ? { extractDetails:    i.extractDetails }    : {}),
+    ...(i.sequenceDetails   ? { sequenceDetails:   i.sequenceDetails }   : {}),
+    ...(i.polymerDetails    ? { polymerDetails:    i.polymerDetails }    : {}),
+    ...(i.surfactantDetails ? { surfactantDetails: i.surfactantDetails } : {}),
+    ...(i.pigmentDetails    ? { pigmentDetails:    i.pigmentDetails }    : {}),
+    ...(i.fragranceDetails  ? { fragranceDetails:  i.fragranceDetails }  : {}),
   };
 }
 
@@ -43,6 +49,7 @@ const list_ingredients = {
         ingredient_class: { type: 'string', description: 'Filter by symbolic class: small-molecule, surfactant, polymer, extract, fragrance, pigment, sequence, mixture.' },
         sequence_contains: { type: 'string', description: 'Case-insensitive substring match on peptide / oligo sequence (e.g. "KTTKS" matches Matrixyl).' },
         taxon_contains: { type: 'string', description: 'Case-insensitive substring match on botanical scientific name (e.g. "Centella").' },
+        inchikey: { type: 'string', description: 'Exact match on the InChIKey identity hash. The first 14 characters are the connectivity hash; pass either the full 27-char key or just the first 14 to dedup-search across tautomers/salts.' },
         limit: { type: 'number', description: 'Max rows (default 100, max 1000).' },
       },
     },
@@ -60,6 +67,14 @@ const list_ingredients = {
       if (args.ingredient_class && norm(i.ingredientClass) !== norm(args.ingredient_class)) return false;
       if (args.sequence_contains && !norm(i.sequence?.raw).includes(norm(args.sequence_contains))) return false;
       if (args.taxon_contains && !norm(i.taxon?.scientificName).includes(norm(args.taxon_contains))) return false;
+      // InChIKey lookup — 14-char prefix matches connectivity only, full
+      // 27-char key matches connectivity + stereo + isotope. Both useful.
+      if (args.inchikey) {
+        const want = String(args.inchikey).trim().toUpperCase();
+        const have = String(i.inchiKey || '').toUpperCase();
+        if (!have) return false;
+        if (want.length === 14 ? !have.startsWith(want) : have !== want) return false;
+      }
       return true;
     });
     return {
@@ -111,4 +126,99 @@ const get_ingredient = {
   },
 };
 
-export const tools = { list_ingredients, get_ingredient };
+// =====================================================================
+// find_by_smarts — SMARTS-pattern substructure search across every
+// ingredient with a SMILES. Lazy-loads @rdkit/rdkit (declared as an
+// optional dependency in package.json so the bare MCP install stays
+// lightweight); returns a clear hint when the dep is missing.
+// =====================================================================
+
+let _rdkitNodePromise = null;
+
+async function _loadRDKitNode() {
+  if (_rdkitNodePromise) return _rdkitNodePromise;
+  _rdkitNodePromise = (async () => {
+    try {
+      // Resolves to the RDKit-JS UMD when @rdkit/rdkit is npm-installed
+      // alongside the MCP server. Throws (caught below) if the optional
+      // dep wasn't installed.
+      const mod = await import('@rdkit/rdkit');
+      const initRDKitModule = mod.default || mod.initRDKitModule || mod;
+      if (typeof initRDKitModule !== 'function') {
+        throw new Error('@rdkit/rdkit loaded but initRDKitModule not callable');
+      }
+      return await initRDKitModule();
+    } catch (e) {
+      _rdkitNodePromise = null;
+      throw e;
+    }
+  })();
+  return _rdkitNodePromise;
+}
+
+const find_by_smarts = {
+  definition: {
+    name: 'find_by_smarts',
+    description: 'Find every ingredient whose SMILES contains the given SMARTS substructure pattern. Requires RDKit-JS (optional dependency); install with `npm install @rdkit/rdkit` in the mcp folder if you get a "not installed" error.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        smarts: { type: 'string', description: 'SMARTS substructure pattern. Examples: "c1ccccc1" (any aromatic 6-ring), "[OX2H1]" (any hydroxyl), "C(=O)O" (carboxylic acid), "[F,Cl,Br,I]" (any halogen), "[#7]" (any nitrogen atom).' },
+        limit: { type: 'number', description: 'Max rows (default 100, max 1000).' },
+      },
+      required: ['smarts'],
+    },
+  },
+  handler: async (args) => {
+    const smarts = String(args?.smarts || '').trim();
+    if (!smarts) return { error: 'smarts pattern is required.' };
+    const { db } = getStore();
+    let rdkit;
+    try {
+      rdkit = await _loadRDKitNode();
+    } catch (e) {
+      return {
+        error: 'RDKit-JS is not installed in the MCP server. Run `npm install @rdkit/rdkit` in the mcp/ folder and try again.',
+        underlying: e?.message || String(e),
+      };
+    }
+    const candidates = (db.ingredients || []).filter(i => i && !i._trashed && i.smiles);
+    const matches = [];
+    let invalid = 0;
+    const limit = Math.min(1000, Math.max(1, args.limit || 100));
+    // Parse the query once.
+    const query = rdkit.get_qmol(smarts);
+    if (!query) return { error: `Invalid SMARTS: "${smarts}"` };
+    try {
+      for (const ing of candidates) {
+        const mol = rdkit.get_mol(ing.smiles);
+        if (!mol) { invalid++; continue; }
+        try {
+          const raw = mol.get_substruct_match(query);
+          if (raw) {
+            try {
+              const parsed = JSON.parse(raw);
+              if (Array.isArray(parsed.atoms) && parsed.atoms.length > 0) {
+                matches.push(_trimIngredient(ing));
+                if (matches.length >= limit) break;
+              }
+            } catch { /* skip parse fail */ }
+          }
+        } finally {
+          mol.delete();
+        }
+      }
+    } finally {
+      query.delete();
+    }
+    return {
+      smarts,
+      totalScanned: candidates.length,
+      invalidSmiles: invalid,
+      returned: matches.length,
+      ingredients: matches,
+    };
+  },
+};
+
+export const tools = { list_ingredients, get_ingredient, find_by_smarts };