@qe-mcp/server-ena 0.1.1 → 0.1.3

package/.gitlab-ci.yml

@@ -60,7 +60,8 @@ verify-tag-version:
   script:
     - |
       TAG_VERSION="${CI_COMMIT_TAG#v}"
-      PKG_VERSION=$(node -e "console.log(require('./package.json').version)")
+      # Parse with sed — the template's alpine image has no node
+      PKG_VERSION=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' package.json | head -1)
       if [ "${TAG_VERSION}" != "${PKG_VERSION}" ]; then
         echo "-----------------------------------------------------------"
         echo "  Tag/package.json mismatch — release blocked"

package/README.md

@@ -30,6 +30,8 @@ Gives Claude a set of ENA tools that run **locally on your machine**. The WASM m
 
 ## Installation
 
+The package is published to the public npm registry — no registry configuration needed.
+
 ### Option A — npx (no install needed)
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac):
@@ -39,24 +41,17 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac):
   "mcpServers": {
     "ena": {
       "command": "npx",
-      "args": ["@qe-mcp/server-ena"]
+      "args": ["--yes", "@qe-mcp/server-ena"]
     }
   }
 }
 ```
 
-Then add the registry to your `~/.npmrc` once:
-
-```bash
-echo "@qe-mcp:registry=https://gitlab.com/api/v4/projects/22522458/packages/npm/" >> ~/.npmrc
-```
-
 Restart Claude Desktop.
 
 ### Option B — global install
 
 ```bash
-echo "@qe-mcp:registry=https://gitlab.com/api/v4/projects/22522458/packages/npm/" >> ~/.npmrc
 npm install -g @qe-mcp/server-ena
 ```
 
@@ -91,6 +86,17 @@ npm install
 }
 ```
 
+### Dev builds
+
+Pre-release builds are published only to the QE GitLab registry with a `dev` tag.
+To use one, add the scope mapping once and pin `@dev`:
+
+```bash
+echo "@qe-mcp:registry=https://gitlab.com/api/v4/projects/22522458/packages/npm/" >> ~/.npmrc
+echo "@qe-libs:registry=https://gitlab.com/api/v4/projects/22522458/packages/npm/" >> ~/.npmrc
+npx --yes @qe-mcp/server-ena@dev
+```
+
 ### Verify
 
 In Claude Desktop, open a new conversation and ask:
@@ -211,10 +217,15 @@ These use `ena_plot` with the cached `model_id` — no refitting.
 
 Each fitting or plotting call returns:
 
-- **Inline PNG** — rendered via jsdom + qeviz + resvg, displayed directly in Claude's response
-- **`interactive_plot`** — path to a local HTML file with the interactive qeviz visualization, openable in any browser
+- **Inline PNG** — an image content block rendered directly in clients that support it (Claude Desktop, Claude web).
+- **`interactive_plot`** — path to a self-contained HTML file with the interactive qeviz visualization, openable in any browser.
+- **`svg_plot`** — path to the rendered SVG (vector; embeddable).
+- **`png_plot`** — path to the rendered PNG (static raster).
 
-The HTML file persists at `/tmp/ena-viz/` until the next system restart.
+The SVG/PNG/HTML file paths let clients that don't render inline image
+blocks (Claude Code, Claude Science) still open or embed the real ENA
+network plot. All files are written to the OS temp dir under `ena-viz/`
+and persist until the next system restart.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qe-mcp/server-ena",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP server for Epistemic Network Analysis — WASM backend, zero Python dependency",
   "type": "module",
   "main": "server.js",

package/server.js

@@ -232,11 +232,11 @@ document.getElementById('vis').setModelData(modelData);
 </html>`;
 }
 
-function writeVizFile(html, name) {
+function writeVizFile(content, name, ext = 'html') {
     const dir = join(tmpdir(), 'ena-viz');
     mkdirSync(dir, { recursive: true });
-    const path = join(dir, `${name}.html`);
-    writeFileSync(path, html, 'utf8');
+    const path = join(dir, `${name}.${ext}`);
+    writeFileSync(path, content);
     return path;
 }
 
@@ -1057,7 +1057,7 @@ const TOOLS = [
             'Returns a model_id that can be passed to ena_plot for additional views (group mean, unit, subtraction, comparison) without re-fitting. ' +
             'Repeated calls with identical parameters return the cached model instantly. ' +
             'Supports rotation="svd" (default) or rotation="mean" (requires group_col, group1_value, group2_value). ' +
-            'An ENA network plot is returned as an inline image in this response — do not generate your own visualization. ' +
+            'An ENA network plot is returned as an inline image, and also written to disk as SVG, PNG, and interactive HTML (paths in svg_plot / png_plot / interactive_plot) for clients that do not render inline images — do not generate your own visualization. ' +
             'PRIVACY: use data_path (file stays local, only model results reach Claude) rather than data_csv (raw data passes through conversation). ' +
             'The WASM model runs entirely on the user\'s machine regardless of which input method is used.',
         inputSchema: {
@@ -1092,7 +1092,7 @@ const TOOLS = [
             'Axis 1 passes through the mean difference between groups. ' +
             'Returns a model_id for use with ena_plot (group, subtraction, comparison, unit views). ' +
             'Repeated calls with identical parameters return the cached model instantly. ' +
-            'An ENA network plot is returned as an inline image in this response — do not generate your own visualization. ' +
+            'An ENA network plot is returned as an inline image, and also written to disk as SVG, PNG, and interactive HTML (paths in svg_plot / png_plot / interactive_plot) for clients that do not render inline images — do not generate your own visualization. ' +
             'PRIVACY: use data_path (file stays local, only model results reach Claude) rather than data_csv (raw data passes through conversation). ' +
             'The WASM model runs entirely on the user\'s machine regardless of which input method is used.',
         inputSchema: {
@@ -1118,7 +1118,7 @@ const TOOLS = [
             '"comparison" — overlay of two group mean networks (requires group1, group2); ' +
             '"subtraction" — difference network g1 − g2 (requires group1, group2, and group_col on the source model); ' +
             '"unit" — individual unit network (requires unit_label). ' +
-            'An ENA network plot is returned as an inline image.',
+            'An ENA network plot is returned as an inline image, and also written to disk as SVG, PNG, and interactive HTML (paths in svg_plot / png_plot / interactive_plot) for clients that do not render inline images.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -1145,9 +1145,69 @@ const server = new Server(
     { capabilities: { tools: {} } }
 );
 
+// ── rena-wasm API adapter ─────────────────────────────────────────────────────
+// rena-wasm ≥ the R-mirroring rewrite returns an R-style ENA set object
+// (lineWeights / points / rotation.nodes / model.unitLabels) instead of the
+// original flat object (networks / centroids / positions / unitLabels).
+// These shims expose the flat field names this server is written against, and
+// are idempotent no-ops on the older flat API.
+
+function adaptModel(m) {
+    if (!m || m.networks !== undefined || m.lineWeights === undefined) return m;
+    return {
+        networks:        m.lineWeights,          // sphere-normed adjacency (nUnits × nConn)
+        centroids:       m.points,               // projected unit positions (nUnits × dims)
+        positions:       m.rotation?.nodes,      // code node positions (nCodes × dims)
+        connectionNames: m.connectionNames,
+        unitLabels:      m.model?.unitLabels ?? m.unitLabels,
+        columnNames:     m.rotation?.columnNames,
+        eigenvalues:     m.rotation?.eigenvalues,
+        nUnits:          m.nUnits,
+        nConnections:    m.nConnections,
+        dims:            m.dims,
+    };
+}
+
+function adaptAccum(a) {
+    if (!a || a.networks !== undefined || a.connectionCounts === undefined) return a;
+    return { ...a, networks: a.connectionCounts };
+}
+
+// A WASM abort (raised by libqe on a degenerate SVD / means rotation) leaves the
+// module instance unusable — every later call would also abort. Detect it,
+// discard the cached instance so the next call reloads a fresh one, and surface
+// an actionable message instead of the raw "Aborted(undefined)".
+function isWasmAbort(e) {
+    return /abort|RuntimeError|out of bounds|memory access|table index/i.test(e?.message ?? '');
+}
+
+const DEGENERATE_FIT_MSG =
+    'ENA rotation could not be computed — the data is too sparse or degenerate. ' +
+    'Common causes: fewer than 2 units have any code co-occurrences within the ' +
+    'stanza window; only one code column; or all units have identical networks. ' +
+    'Use ena_accumulate to inspect the raw co-occurrence networks, and check that ' +
+    'you have 2+ code columns that actually co-occur and 2+ units with non-empty networks.';
+
 let enaPromise = null;
 function getENA() {
-    if (!enaPromise) enaPromise = loadENA();
+    if (!enaPromise) enaPromise = loadENA().then(ena => {
+        const guard = (fn, adapt) => (rows, opts) => {
+            try {
+                return adapt(fn.call(ena, rows, opts));
+            } catch (e) {
+                if (isWasmAbort(e)) {
+                    enaPromise = null;              // force a fresh WASM instance next call
+                    throw new Error(DEGENERATE_FIT_MSG);
+                }
+                throw e;
+            }
+        };
+        return {
+            ...ena,
+            fit:        guard(ena.fit,        adaptModel),
+            accumulate: guard(ena.accumulate, adaptAccum),
+        };
+    });
     return enaPromise;
 }
 
@@ -1177,16 +1237,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const content = [{ type: 'text', text: JSON.stringify(cleanResult, null, 2) }];
 
         if (_vizData) {
+            const slug = [cleanResult.model_id, cleanResult.plot_type].filter(Boolean).join('_') || name;
+            const artifacts = {};     // fields to merge into the text block
             let renderError = null;
+            let svg = null;
+
             try {
-                const svg = await renderSVG(_vizData, _vizOpts ?? {});
+                svg = await renderSVG(_vizData, _vizOpts ?? {});
                 if (svg) {
                     const png = new Resvg(svg, { fitTo: { mode: 'width', value: SVG_SIZE }, background: '#ffffff' }).render().asPng();
+                    // Inline image block — rendered by clients that support it (Claude Desktop / web).
                     content.unshift({
                         type:     'image',
                         data:     png.toString('base64'),
                         mimeType: 'image/png',
                     });
+                    // Also write SVG + PNG files for clients that don't render inline images
+                    // (Claude Code, Claude Science) so the real plot can be opened/embedded.
+                    try { artifacts.svg_plot = writeVizFile(svg, slug, 'svg'); }
+                    catch (e) { process.stderr.write(`[ena-mcp] SVG write failed: ${e.message}\n`); }
+                    try { artifacts.png_plot = writeVizFile(png, slug, 'png'); }
+                    catch (e) { process.stderr.write(`[ena-mcp] PNG write failed: ${e.message}\n`); }
                 } else {
                     renderError = 'renderSVG returned null (qe-graph svg_element not found — jsdom/qeviz may have failed silently)';
                 }
@@ -1195,28 +1266,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             if (renderError) {
                 process.stderr.write(`[ena-mcp] render failed: ${renderError}\n`);
-                // Surface the failure in the text block so it's visible in chat
-                const parsed = JSON.parse(content[0].text);
-                parsed._render_error = renderError;
-                content[0].text = JSON.stringify(parsed, null, 2);
+                artifacts._render_error = renderError;
             }
 
-            // Also write an HTML file for clients that don't render inline images (e.g. Claude Code).
-            // This is additive — the image block above still works for clients that do (e.g. Claude Chat).
+            // Self-contained interactive HTML for clients that don't render inline images.
             try {
                 const vizLabel = cleanResult.label ?? name;
-                const slug = [cleanResult.model_id, cleanResult.plot_type].filter(Boolean).join('_') || name;
                 const html = generateHTML(_vizData, vizLabel, _vizOpts ?? {});
-                const htmlPath = writeVizFile(html, slug);
-                const textBlock = content.find(c => c.type === 'text');
-                if (textBlock) {
-                    const parsed = JSON.parse(textBlock.text);
-                    parsed.interactive_plot = htmlPath;
-                    textBlock.text = JSON.stringify(parsed, null, 2);
-                }
+                artifacts.interactive_plot = writeVizFile(html, slug, 'html');
             } catch (e) {
                 process.stderr.write(`[ena-mcp] HTML write failed: ${e.message}\n`);
             }
+
+            // Merge all artifact paths into the text block in one pass.
+            const textBlock = content.find(c => c.type === 'text');
+            if (textBlock && Object.keys(artifacts).length) {
+                const parsed = JSON.parse(textBlock.text);
+                Object.assign(parsed, artifacts);
+                textBlock.text = JSON.stringify(parsed, null, 2);
+            }
         }
 
         return { content };