formlab-mcp 0.6.36 → 0.6.38

package/README.md

@@ -37,7 +37,7 @@ Ask Claude (or another MCP client) things like:
 | `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. Filters: `type`, `record`, `linked`, `query`, `lot`, `format`, `expiry`, `expiring_within_days`, `without_expiry`, `uploaded_within_days`. 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_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) |
@@ -66,8 +66,8 @@ Ask Claude (or another MCP client) things like:
 | `get_test_panel` | One Test Panel: ordered parameters with resolved method UIDs + specs, plus `usage` (reports created from it) and `performanceByParameter` |
 | `list_projects` | Filtered list of projects (the buckets formulations are filed under) + per-project formulation count. Filters: `status`, `name_contains` |
 | `get_project` | Full project record + the formulations filed under it |
-| `list_notebook_entries` | ELN feed — dated authored notes attached to records. Filters: `entity_type`, `entity_id`, `author`, `text_contains`, `since`, `until` |
-| `get_notebook_entry` | One notebook entry — full body, author, attachment metadata, resolved linked record |
+| `list_notebook_entries` | ELN feed — dated authored notes attached to records. Append-only: a withdrawn note is kept with `retracted` = {at, by, reason}. Filters: `entity_type`, `entity_id`, `author`, `text_contains`, `since`, `until`, `retracted` |
+| `get_notebook_entry` | One notebook entry — full body, author, attachment metadata, resolved linked record, and `retracted` when withdrawn |
 
 ## Install
 

package/package.json

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

package/tools/analytics.js

@@ -164,8 +164,8 @@ const list_test_results = {
         const found = (t.measurements || []).some(m => {
           if (args.parameter && !norm(m.parameter).includes(pn)) return false;
           if (hasRange) {
-            const v = parseFloat(m.value);
-            if (!Number.isFinite(v)) return false;
+            const v = _mcpRepNumber(m);   // a curve's final value, not its point count (13a)
+            if (v == null) return false;
             if (args.value_min != null && v < args.value_min) return false;
             if (args.value_max != null && v > args.value_max) return false;
           }
@@ -352,7 +352,9 @@ const get_doe_matrix = {
     const cellParamValue = (r, col) => {
       const ms = r.measurements.filter(m => m.parameter === col.id && (col.cond == null || _mcpCondSig(m) === col.cond));
       if (!ms.length) return null;
-      const nums = ms.map(m => parseFloat(m.value)).filter(v => isFinite(v));
+      // The app's DOE Matrix numbers (13a): a curve's final value, a
+      // distribution's D50, an ordinal's 1-based rank; text → its first reading.
+      const nums = ms.map(m => _mcpRepNumber(m, { ordinal: 'rank' })).filter(v => v != null);
       if (!nums.length) return ms[0].value ?? null;
       const mean = nums.reduce((s, v) => s + v, 0) / nums.length;
       return +mean.toFixed(4);
@@ -405,18 +407,44 @@ const get_doe_matrix = {
 // so a parameter measured 3× on one occasion counts once in failure rates and
 // coverage, exactly as Test Analytics does.
 const FAIL_MIN_N = 5;   // app: _TA_FAIL_MIN_N — rates on fewer readings are "low n"
-function _mcpRepNumber(m) {
-  const type = m.type || 'scalar';
-  if (type === 'time_series' && Array.isArray(m.points) && m.points.length) {
+// One number per measurement — the app's flMeasNum (js/utils.js, 13a), kept
+// in step. Never parseFloat(m.value): a saved time series / distribution has
+// "12 points" / "8 bins" there, and an ordinal label "6B" parses to 6.
+//   scalar → value; time_series → opts.ts ('final' default | 'initial' | 'peak');
+//   distribution → opts.dist ('D50' default, a named bin only — no stand-in);
+//   ordinal → null, or with opts.ordinal === 'rank' its 1-based scale position;
+//   categorical → null.
+function _mcpMeasType(m) {
+  const T = ['scalar', 'ordinal', 'categorical', 'time_series', 'distribution'];
+  if (m && m.type && T.includes(m.type)) return m.type;
+  return m && m.valueType === 'Categorical' ? 'categorical' : 'scalar';
+}
+function _mcpRepNumber(m, opts) {
+  const o = opts || {};
+  if (!m) return null;
+  const type = _mcpMeasType(m);
+  if (type === 'time_series') {
+    if (!Array.isArray(m.points) || !m.points.length) return null;
     const agg = _mcpTsAggregate(m.points);
-    const last = agg[agg.length - 1];
-    return last ? last.mean : null;
+    if (!agg.length) return null;
+    const means = agg.map(g => g.mean);
+    const red = o.ts || 'final';
+    const v = red === 'initial' ? means[0] : red === 'peak' ? Math.max(...means) : means[means.length - 1];
+    return isFinite(v) ? v : null;
   }
-  if (type === 'distribution' && Array.isArray(m.bins) && m.bins.length) {
-    const d50 = m.bins.find(b => String(b.label || '').toUpperCase().replace(/\s/g, '') === 'D50');
-    const v = d50 ? parseFloat(d50.value) : NaN;
+  if (type === 'distribution') {
+    if (!Array.isArray(m.bins) || !m.bins.length) return null;
+    const want = String(o.dist || 'D50').toUpperCase();
+    const b = m.bins.find(x => String((x && x.label) || '').toUpperCase().replace(/\s/g, '') === want);
+    const v = b ? parseFloat(b.value) : NaN;
     return isFinite(v) ? v : null;
   }
+  if (type === 'ordinal') {
+    if (o.ordinal !== 'rank' || !Array.isArray(m.scale)) return null;
+    const i = m.scale.map(x => String(x).trim().toUpperCase()).indexOf(String(m.value == null ? '' : m.value).trim().toUpperCase());
+    return i >= 0 ? i + 1 : null;
+  }
+  if (type === 'categorical') return null;
   const v = parseFloat(m.value);
   return isFinite(v) ? v : null;
 }
@@ -1153,6 +1181,7 @@ const get_stability = {
     const paramLc = (args.parameter || '').trim().toLowerCase();
     if (!paramLc) return { error: 'parameter is required.' };
     const points = [];
+    const skipped = { ordinal: 0, categorical: 0 };
     let specMin = null, specMax = null, unit = '';
     // Each reading keeps the spec it was judged by (reading → panel row →
     // method). Mirrors the app: one band only when they all agree; 2+ distinct
@@ -1165,11 +1194,12 @@ const get_stability = {
       if (!Number.isFinite(date.getTime())) return;
       (t.measurements || []).forEach(m => {
         if ((m.parameter || '').trim().toLowerCase() !== paramLc) return;
-        let value = parseFloat(m.value);
-        if (!Number.isFinite(value) && Array.isArray(m.points) && m.points.length) {
-          const last = m.points[m.points.length - 1]; value = parseFloat(last && (last.value ?? last.y));   // time-series → final
-        }
-        if (!Number.isFinite(value)) return;
+        // As the app's Stability chart (13a): a curve → its final value (not
+        // "12 points" → 12), and ordinal / text readings left out and counted.
+        const _ty = _mcpMeasType(m);
+        if (_ty === 'ordinal' || _ty === 'categorical') { skipped[_ty]++; return; }
+        const value = _mcpRepNumber(m);
+        if (value == null) return;
         if (m.unit && !unit) unit = m.unit;
         const rs = _resolveSpec(m, t.templateId), ac = rs.spec;
         const sp = (ac && (Number.isFinite(ac.min) || Number.isFinite(ac.max))) ? { min: Number.isFinite(ac.min) ? ac.min : null, max: Number.isFinite(ac.max) ? ac.max : null } : null;
@@ -1208,7 +1238,7 @@ const get_stability = {
       points.push({ date: new Date(g[0].day), value, cond: g[0].cond, spec: (g.find(r => r.spec) || {}).spec || null, readings: g.length });
     });
     points.sort((a, b) => (a.date - b.date) || a.cond.localeCompare(b.cond));
-    if (!points.length) return { error: `No dated "${args.parameter}" measurements on ${entity.uid || entity.id}.` };
+    if (!points.length) return { error: `No dated numeric "${args.parameter}" measurements on ${entity.uid || entity.id}.${skipped.ordinal || skipped.categorical ? ` ${skipped.ordinal} ordinal and ${skipped.categorical} text reading(s) exist but have no number to trend — use list_test_results / find_failures for their pass/fail.` : ''}` };
 
     const spec = { min: specMin, max: specMax };
     // Target shelf life: the formula's own Shelf life, else the workspace
@@ -1275,14 +1305,14 @@ const get_stability = {
 
     return {
       entity: { type: entityType, uid: entity.uid, name: entity.name || entity.uid },
-      parameter: args.parameter, unit, spec, ...(specVaries ? { specVaries, specNote: 'Readings were judged against different specs (different panels): no single band, no shelf-life projection; each reading keeps its own pass/fail.' } : {}), pointCount: points.length, byCondition: split, series,
+      parameter: args.parameter, unit, spec, ...((skipped.ordinal || skipped.categorical) ? { skipped, skippedNote: 'Ordinal (ranked scale) and text readings have no number to trend and are left out, as in the app.' } : {}), ...(specVaries ? { specVaries, specNote: 'Readings were judged against different specs (different panels): no single band, no shelf-life projection; each reading keeps its own pass/fail.' } : {}), pointCount: points.length, byCondition: split, series,
       targetShelfLife: target ? { months: target.months, source: target.source } : null,
       note: 'shelfLife.fromT0Months / ci95FromT0Months are the projected shelf life counted from the first test (T0): point estimate and the conservative (ICH Q1E) 95%-bound crossing. remainingMonths / ci95Months are the same, counted from the last test. verdict compares against targetShelfLife: "short" = the trend crosses spec before the target, "marginal" = the trend clears it but the 95% bound does not, "meets" = both clear it; null = no target set (then concern is by time left: medium <3 mo or overdue, else info). A projection never reaches \"high\": high is reserved for a MEASURED out-of-spec value (spec.latestInSpec=false). short/overdue → medium, marginal/meets → info. overdue=true means projectedCrossDate is already past today (time left runs from the last test), so the sample is probably out of spec now — recommend a re-test. reportable=false means the app shows no projection (R² < 0.3, crossing already past, or beyond 5 years). Numbers are computed here — narrate them, do not recompute.',
     };
   },
 };
 
-export { _evalPassFail, _resolveSpec, _shelfLife, _shelfLifeAssess, _mcpCondTags, _mcpArmNames, _mcpCondDefaultScore };
+export { _mcpRepNumber, _mcpMeasType, _evalPassFail, _resolveSpec, _shelfLife, _shelfLifeAssess, _mcpCondTags, _mcpArmNames, _mcpCondDefaultScore };
 export const tools = {
   list_test_results,
   get_test_result,

package/tools/designspace.js

@@ -27,6 +27,7 @@
 // ============================================================
 
 import { getStore, resolveById, flattenComposition } from '../data.js';
+import { _mcpRepNumber } from './analytics.js';
 
 // ---- composition helper -----------------------------------------------------
 // Ingredient wt-% map for one formula, mirroring the app's _asmIngredientMap:
@@ -344,12 +345,20 @@ function _roleCandidates(forms, roleMaps) {
   });
   return out.sort((a, b) => b.score - a.score);
 }
-// A formula's value for a measured parameter: the mean of every numeric
-// reading of it across the formula's samples (the app's _asmFormulaValueForCol).
+// A formula's value for a measured parameter, as the app's
+// _asmFormulaValueForCol (13a): readings of the primary run condition (the one
+// with the most readings), each as the DOE Matrix reads it (a curve's final
+// value, a distribution's D50, an ordinal's rank), then their mean.
 function _paramValue(f, param, db) {
   const sids = new Set((db.samples || []).filter(s => s.formulationId === f.id).map(s => s.id));
-  const vals = [];
-  (db.testResults || []).forEach(t => { if (!sids.has(t.sampleId)) return; (t.measurements || []).forEach(m => { if (m.parameter === param) { const v = parseFloat(m.value); if (!isNaN(v)) vals.push(v); } }); });
+  const ms = [];
+  (db.testResults || []).forEach(t => { if (!sids.has(t.sampleId)) return; (t.measurements || []).forEach(m => { if (m.parameter === param) ms.push(m); }); });
+  const sig = (m) => { const c = m && m.conditions; return c && typeof c === 'object' ? Object.keys(c).filter(k => c[k] != null && c[k] !== '').sort().map(k => k + '=' + c[k]).join('; ') : ''; };
+  const byCond = new Map();
+  ms.forEach(m => { if (_mcpRepNumber(m) == null) return; const k = sig(m); byCond.set(k, (byCond.get(k) || 0) + 1); });
+  const primary = [...byCond.entries()].sort((a, b) => b[1] - a[1])[0];
+  const pool = primary ? ms.filter(m => sig(m) === primary[0]) : ms;
+  const vals = pool.map(m => _mcpRepNumber(m, { ordinal: 'rank' })).filter(v => v != null);
   return vals.length ? vals.reduce((a, b) => a + b, 0) / vals.length : null;
 }
 function _spearman(xs, ys) {

package/tools/documents.js

@@ -60,7 +60,7 @@ function allDocuments(db) {
       lot: d.lotNumber || '', version: d.version != null ? String(d.version) : '', source: d.source || '',
       expiryDate: d.expiryDate || null, expiryStatus: ex.status, daysToExpiry: ex.daysToExpiry,
       sizeKb: Number.isFinite(+d.size) && d.size != null ? Math.round(+d.size / 102.4) / 10 : null,
-      uploadedAt: d.uploadedAt || null,
+      uploadedAt: d.uploadedAt || null, addedBy: d.addedBy || null,
     });
   }));
   const testsById = new Map((db.testResults || []).map(t => [t.id, t]));
@@ -71,7 +71,7 @@ function allDocuments(db) {
       record: 'test', linked: (t ? (t.uid || t.id) : 'Test') + (a.measurementParameter ? ' · ' + a.measurementParameter : ''), linkedId: t ? (t.uid || t.id) : null,
       lot: '', version: '', source: '', expiryDate: null, expiryStatus: 'none', daysToExpiry: null,
       sizeKb: Number.isFinite(+a.fileSize) && a.fileSize != null ? Math.round(+a.fileSize / 102.4) / 10 : null,
-      uploadedAt: a.uploadedAt || null,
+      uploadedAt: a.uploadedAt || null, addedBy: a.addedBy || null,
     });
   });
   (db.notebookEntries || []).filter(live).forEach(ne => (ne.attachments || []).forEach(att => {
@@ -83,7 +83,7 @@ function allDocuments(db) {
       record: 'notebook', linked: rec ? (rec.name || rec.uid || '') : (ne.entityType || 'note'), linkedId: rec ? (rec.uid || rec.id) : null,
       lot: '', version: '', source: '', expiryDate: null, expiryStatus: 'none', daysToExpiry: null,
       sizeKb: Number.isFinite(+att.size) && att.size != null ? Math.round(+att.size / 102.4) / 10 : null,
-      uploadedAt: att.uploadedAt || null,
+      uploadedAt: att.uploadedAt || null, addedBy: att.addedBy || ne.author || null,   // a note's file is its author's
     });
   }));
   Object.entries(ATTACH_COLL).forEach(([etype, coll]) => (db[coll] || []).filter(live).forEach(rec => (rec.fileAttachments || []).forEach(a => {
@@ -95,7 +95,7 @@ function allDocuments(db) {
       ...(isLink && a.url ? { url: a.url } : {}),
       lot: '', version: '', source: '', expiryDate: null, expiryStatus: 'none', daysToExpiry: null,
       sizeKb: (!isLink && Number.isFinite(+a.size) && a.size != null) ? Math.round(+a.size / 102.4) / 10 : null,
-      uploadedAt: a.createdAt || null,
+      uploadedAt: a.createdAt || null, addedBy: a.addedBy || null,
     });
   })));
   return out;
@@ -121,7 +121,7 @@ function summary(db, docs) {
 const list_documents = {
   definition: {
     name: 'list_documents',
-    description: 'The workspace document register — same list as the app\'s Documents page: ingredient SDS / PDS / CoA / other files (with lot, version, source, expiry), test-result and notebook attachments, and per-record uploads and links (formulas, batches, samples, suppliers, equipment…). Returns file METADATA only (never the text inside a file). Filters combine. The summary block matches the page\'s tiles: expired, expiring in 30 days, SDS/CoA without an expiry date, ingredients missing an SDS (+ coverage %), lots in stock without a CoA, files added in the last 7 days. For the lots themselves use list_lots with missing_coa: true.',
+    description: 'The workspace document register — same list as the app\'s Documents page: ingredient SDS / PDS / CoA / other files (with lot, version, source, expiry), test-result and notebook attachments, and per-record uploads and links (formulas, batches, samples, suppliers, equipment…). Returns file METADATA only (never the text inside a file), including addedBy (who added it — null for files added before that was recorded) and uploadedAt. Filters combine. The summary block matches the page\'s tiles: expired, expiring in 30 days, SDS/CoA without an expiry date, ingredients missing an SDS (+ coverage %), lots in stock without a CoA, files added in the last 7 days. For the lots themselves use list_lots with missing_coa: true.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -135,6 +135,7 @@ const list_documents = {
         expiring_within_days: { type: 'number', description: 'Only documents whose expiry date is within this many days (already expired included).' },
         without_expiry: { type: 'boolean', description: 'true = only SDS / CoA files with no expiry date (the "SDS / CoA without expiry" tile).' },
         uploaded_within_days: { type: 'number', description: 'Only files uploaded within this many days.' },
+        added_by: { type: 'string', description: 'Who added the file: case-insensitive substring of their email / name. Files from before this was recorded have none and never match.' },
         limit: { type: 'number', description: 'Max rows (default 200, max 1000).' },
       },
     },
@@ -156,6 +157,7 @@ const list_documents = {
       if (args.expiring_within_days != null && !(d.daysToExpiry != null && d.daysToExpiry <= args.expiring_within_days)) return false;
       if (args.without_expiry === true && !(d.record === 'ingredient' && d.expiryStatus === 'none' && (d.type === 'SDS' || d.type === 'COA'))) return false;
       if (args.uploaded_within_days != null && !(d.ageDays != null && d.ageDays <= args.uploaded_within_days)) return false;
+      if (args.added_by && !norm(d.addedBy).includes(norm(args.added_by))) return false;
       return true;
     }).sort((a, b) => String(b.uploadedAt || '').localeCompare(String(a.uploadedAt || '')));
     return { summary: summary(db, all), totalMatching: rows.length, returned: Math.min(rows.length, limit), documents: rows.slice(0, limit) };

package/tools/notebook.js

@@ -46,6 +46,10 @@ function _trimEntry(e, db, { full = false } = {}) {
     updatedAt: e.updatedAt || null,
     author: e.author || '',
     attachmentCount: atts.length,
+    // Withdrawn by its author or the workspace owner (append-only notebook):
+    // the note is kept, but it is not a finding. null when not retracted.
+    retracted: (e.retracted && typeof e.retracted === 'object')
+      ? { at: e.retracted.at || null, by: e.retracted.by || '', reason: e.retracted.reason || '' } : null,
   };
   if (!full) return { ...base, body: (e.body || '').slice(0, 240) };
   return {
@@ -58,7 +62,7 @@ function _trimEntry(e, db, { full = false } = {}) {
 const list_notebook_entries = {
   definition: {
     name: 'list_notebook_entries',
-    description: 'List ELN notebook entries — dated, authored notes attached to records — optionally filtered by the record they hang off (entity_type + entity_id), author, text, or date range. Newest first. Use get_notebook_entry for the full body + attachments.',
+    description: 'List ELN notebook entries — dated, authored notes attached to records — optionally filtered by the record they hang off (entity_type + entity_id), author, text, or date range. Newest first. Entries are append-only: a withdrawn one is kept with retracted = {at, by, reason} — treat it as withdrawn, not as a finding. Use get_notebook_entry for the full body + attachments.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -68,6 +72,7 @@ const list_notebook_entries = {
         text_contains: { type: 'string', description: 'Case-insensitive substring on the note body.' },
         since: { type: 'string', description: 'ISO date/time — only entries at or after this timestamp.' },
         until: { type: 'string', description: 'ISO date/time — only entries at or before this timestamp.' },
+        retracted: { type: 'boolean', description: 'false = only notes that stand (leave out retracted ones); true = only retracted notes. Omit for both.' },
         limit: { type: 'number', description: 'Max rows (default 100, max 1000).' },
       },
     },
@@ -91,6 +96,7 @@ const list_notebook_entries = {
       if (wantEntityId && e.entityId !== wantEntityId) return false;
       if (args.author && !_norm(e.author).includes(_norm(args.author))) return false;
       if (args.text_contains && !_norm(e.body).includes(_norm(args.text_contains))) return false;
+      if (typeof args.retracted === 'boolean' && (!!(e.retracted && typeof e.retracted === 'object')) !== args.retracted) return false;
       if (sinceMs != null || untilMs != null) {
         const t = Date.parse(_entryTs(e));
         if (!isFinite(t)) return false;
@@ -110,7 +116,7 @@ const list_notebook_entries = {
 const get_notebook_entry = {
   definition: {
     name: 'get_notebook_entry',
-    description: 'Get one ELN notebook entry by id — full note body, author, timestamp, the record it is attached to (resolved to uid/name), and attachment metadata (filename / type). Attachment binaries are not returned.',
+    description: 'Get one ELN notebook entry by id — full note body, author, timestamp, the record it is attached to (resolved to uid/name), attachment metadata (filename / type), and retracted = {at, by, reason} when the note was withdrawn. Attachment binaries are not returned.',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Internal id of the notebook entry.' } },