@qe-mcp/server-ena 0.1.2 → 0.1.4

package/README.md

@@ -217,10 +217,25 @@ 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
-
-The HTML file persists at `/tmp/ena-viz/` until the next system restart.
+- **`svg_plot`** — path to the rendered SVG (vector; embeddable). Always produced.
+- **`interactive_plot`** — path to a self-contained HTML file with the interactive qeviz visualization, openable in any browser. Always produced.
+- **`png_plot`** — path to the rendered PNG (static raster). Only when the optional PNG rasterizer is installed.
+- **Inline PNG** — an image content block rendered directly in clients that support it (Claude Desktop, Claude web). Only when the optional PNG rasterizer is installed.
+
+The file-path outputs 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.
+
+### Optional PNG rendering
+
+PNG output (`png_plot` and the inline image block) is powered by
+[`@resvg/resvg-js`](https://www.npmjs.com/package/@resvg/resvg-js), a
+native module listed under `optionalDependencies`. It is installed
+automatically by `npm install` on supported platforms. When it is absent
+— e.g. a cross-platform bundle built without optional dependencies — the
+server logs a notice and produces `svg_plot` + `interactive_plot` only;
+no error, no crash.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qe-mcp/server-ena",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "MCP server for Epistemic Network Analysis — WASM backend, zero Python dependency",
   "type": "module",
   "main": "server.js",
@@ -14,9 +14,11 @@
     "@modelcontextprotocol/sdk": "^1.4.0",
     "@qe-libs/qeviz": "^0.1.0",
     "@qe-libs/rena-wasm": "^0.1.0",
-    "@resvg/resvg-js": "^2.6.2",
     "jsdom": "^25.0.1"
   },
+  "optionalDependencies": {
+    "@resvg/resvg-js": "^2.6.2"
+  },
   "keywords": [
     "mcp",
     "ena",

package/server.js

@@ -232,18 +232,38 @@ 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;
 }
 
 // ── jsdom SVG renderer ────────────────────────────────────────────────────────
 
 import { JSDOM } from 'jsdom';
-import { Resvg } from '@resvg/resvg-js';
+
+// @resvg/resvg-js is a native (platform-specific) addon and is an OPTIONAL
+// dependency: it powers the inline PNG image block and the png_plot file. When
+// it is absent — e.g. a cross-platform .mcpb bundle built without optional deps,
+// or a platform with no prebuilt binary — the server still produces the SVG and
+// interactive HTML outputs. Loaded lazily so its absence never breaks startup.
+let _Resvg;   // undefined = not yet attempted; null = unavailable
+async function getResvg() {
+    if (_Resvg === undefined) {
+        try {
+            ({ Resvg: _Resvg } = await import('@resvg/resvg-js'));
+        } catch {
+            _Resvg = null;
+            process.stderr.write(
+                '[ena-mcp] @resvg/resvg-js not available — inline PNG and png_plot ' +
+                'disabled; svg_plot and interactive_plot are still produced.\n'
+            );
+        }
+    }
+    return _Resvg;
+}
 
 const SVG_SIZE = 600;
 
@@ -1057,7 +1077,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. ' +
+            'The ENA network plot is written to disk as SVG (svg_plot) and interactive HTML (interactive_plot), and — when the optional PNG rasterizer is installed — also as PNG (png_plot) plus an inline image block. Use these paths to show the plot; 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 +1112,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. ' +
+            'The ENA network plot is written to disk as SVG (svg_plot) and interactive HTML (interactive_plot), and — when the optional PNG rasterizer is installed — also as PNG (png_plot) plus an inline image block. Use these paths to show the plot; 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 +1138,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.',
+            'The ENA network plot is written to disk as SVG (svg_plot) and interactive HTML (interactive_plot), plus PNG (png_plot) and an inline image when the optional PNG rasterizer is installed.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -1237,16 +1257,31 @@ 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();
-                    content.unshift({
-                        type:     'image',
-                        data:     png.toString('base64'),
-                        mimeType: 'image/png',
-                    });
+                    // SVG file — always available (pure JS/WASM), vector, embeddable.
+                    try { artifacts.svg_plot = writeVizFile(svg, slug, 'svg'); }
+                    catch (e) { process.stderr.write(`[ena-mcp] SVG write failed: ${e.message}\n`); }
+
+                    // PNG (inline image block + png_plot file) only when the optional
+                    // native rasterizer is present. Absent in cross-platform bundles.
+                    const Resvg = await getResvg();
+                    if (Resvg) {
+                        const png = new Resvg(svg, { fitTo: { mode: 'width', value: SVG_SIZE }, background: '#ffffff' }).render().asPng();
+                        content.unshift({
+                            type:     'image',
+                            data:     png.toString('base64'),
+                            mimeType: 'image/png',
+                        });
+                        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)';
                 }
@@ -1255,28 +1290,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 };