@qe-mcp/server-ena 0.1.3 → 0.1.5

package/README.md

@@ -217,15 +217,25 @@ These use `ena_plot` with the cached `model_id` — no refitting.
 
 Each fitting or plotting call returns:
 
-- **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 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.
+- **`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.3",
+  "version": "0.1.5",
   "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

@@ -243,7 +243,27 @@ function writeVizFile(content, name, ext = 'html') {
 // ── 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;
 
@@ -283,7 +303,23 @@ async function renderSVG(modelData, opts = {}) {
     if (!svgHtml.includes('xmlns=')) {
         svgHtml = svgHtml.replace('<svg', '<svg xmlns="http://www.w3.org/2000/svg"');
     }
-    return svgHtml;
+    return withWhiteBackground(svgHtml);
+}
+
+// The qeviz SVG has a transparent background, which makes the plot invisible in
+// dark-mode viewers. Insert an opaque white rect as the first child (behind all
+// content), sized to the SVG's viewBox so it covers the full canvas.
+function withWhiteBackground(svgHtml) {
+    const openTagMatch = svgHtml.match(/<svg[^>]*>/);
+    if (!openTagMatch) return svgHtml;
+    const openTag = openTagMatch[0];
+
+    const vb = openTag.match(/viewBox\s*=\s*["']\s*([-\d.]+)\s+([-\d.]+)\s+([-\d.]+)\s+([-\d.]+)\s*["']/);
+    const rect = vb
+        ? `<rect x="${vb[1]}" y="${vb[2]}" width="${vb[3]}" height="${vb[4]}" fill="#ffffff"/>`
+        : `<rect x="0" y="0" width="100%" height="100%" fill="#ffffff"/>`;
+
+    return svgHtml.replace(openTag, openTag + rect);
 }
 
 // ── Model / accumulation cache ────────────────────────────────────────────────
@@ -1057,7 +1093,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, 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. ' +
+            '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 +1128,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, 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. ' +
+            '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 +1154,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, 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.',
+            '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: {
@@ -1245,19 +1281,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             try {
                 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.
+                    // 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`); }
-                    try { artifacts.png_plot = writeVizFile(png, slug, 'png'); }
-                    catch (e) { process.stderr.write(`[ena-mcp] PNG 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)';
                 }