@qe-mcp/ena 0.1.17 → 0.1.18

package/README.md

@@ -157,6 +157,42 @@ manual install under [Get started](#get-started). Don't edit
 be pasted. A plain-text copy of this page is at
 [llms.txt](https://qe-libs.org/mcp/qe-mcp-ena/llms.txt).
 
+### Hosting it (remote MCP)
+
+Everything above runs the server on the user's own machine, which is what
+keeps their data there. For web clients that can only reach remote MCP
+endpoints (Claude.ai custom connectors, ChatGPT connectors, Gemini custom
+apps), the same package can serve MCP over streamable HTTP instead:
+
+```bash
+npx --yes @qe-mcp/ena --http --port 8000 --host 0.0.0.0
+```
+
+The endpoint is `/mcp`; `GET /healthz` answers for probes. `--port` and
+`--host` fall back to `$PORT` and `$HOST`; `--max-body-mb` caps request size
+(default 25).
+
+A hosted server has no access to anyone's files, so this mode is a different
+privacy promise, and it says so to the model. In `--http` mode:
+
+- Data arrives inline as `data_csv`; `data_path` is refused. The server
+  processes it in memory and stores nothing.
+- `ena_profile`, `ena_tables`, `ena_lines` and `ena_export` are not offered
+  (they read or write files), and the prompts are not listed (they take a
+  path). Plots come back as the inline PNG plus the SVG as text; no files are
+  written.
+- The server's instructions tell the model to say that the data leaves the
+  user's machine and must be de-identified, and to get their OK first.
+- `model_id`s carry a random suffix so one conversation cannot plot another's
+  model.
+
+Each request is answered statelessly, so any replica can take any request,
+but fitted models are cached in the process that fitted them: run one
+replica, or use sticky sessions, for `model_id`s to stay valid across calls.
+Put TLS and whatever authentication or rate limiting you need in front of it;
+the server itself does neither. `node test-http.mjs` starts it on a free port
+and checks all of the above.
+
 ## Prompts
 
 Describe what you want; the assistant picks the tools. These use the columns
@@ -299,7 +335,7 @@ rule such as `Read(./data/**)` in `.claude/settings.json`, plus the hook below.
 **Results come only from the server.** Every number and plot should come from
 this server, never from code the assistant writes; the server and every tool
 error say so. Each result carries `provenance` (e.g.
-`@qe-mcp/ena 0.1.17 (rena-wasm 0.1.14)`), the interactive plot names it
+`@qe-mcp/ena 0.1.18 (rena-wasm 0.1.14)`), the interactive plot names it
 in its footer and the SVG in its `<desc>`. A plot or table without it didn't
 come from this server.
 

package/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.2",
   "name": "qe-mcp-ena",
   "display_name": "ENA — Epistemic Network Analysis",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Epistemic Network Analysis on tabular coded data. Runs entirely on your machine — data never leaves your computer.",
   "long_description": "Run Epistemic Network Analysis (ENA), ordered network analysis (ONA) and transmodal analysis (TMA) on your coded data from a conversation with Claude. No R or Python to install.\n\n**Your data stays on your machine**\n\n- The analysis runs locally. Only results — networks, points, statistics and plots — go back to the conversation.\n- Give Claude a file path rather than pasting data; the server reads the file itself.\n- It makes no network connections, starts no other programs, and writes files only when you ask for an export.\n\n**About the install warning**\n\nClaude Desktop shows \"access to everything on your computer\" for every extension outside Anthropic's reviewed directory. It means you are trusting the source, as with any program you install. The source is published on npm as @qe-mcp/ena.\n\nDocumentation and example prompts: https://qe-libs.org/mcp/qe-mcp-ena/",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qe-mcp/ena",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Epistemic Network Analysis for Claude and other assistants — runs on your machine",
   "repository": {
     "type": "git",
@@ -26,10 +26,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.4.0",
-    "@qe-libs/qeviz": "0.6.0",
+    "@qe-libs/qeviz": "0.7.0",
     "@qe-libs/rena-wasm": "^0.1.14",
-    "@resvg/resvg-wasm": "^2.6.2",
-    "jsdom": "^25.0.1"
+    "@resvg/resvg-wasm": "^2.6.2"
   },
   "optionalDependencies": {
     "@resvg/resvg-js": "^2.6.2"

package/server.js

@@ -29,6 +29,39 @@ import { connectionWindows, viewerHtml } from './lines.js';
 import { defaultTensor } from '@qe-libs/rena-wasm/src/tensor.js';
 import { Server }               from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createServer as createHttpServer } from 'http';
+import { randomBytes } from 'crypto';
+
+// ── Mode ──────────────────────────────────────────────────────────────────────
+// Default: stdio, launched by the client on the user's machine (the bundle,
+// npx, claude mcp add). `--http` serves MCP over streamable HTTP instead, for
+// hosting the server where web clients (Claude.ai, ChatGPT, Gemini) can reach
+// it. In that mode there is no user disk: data arrives inline, nothing is
+// written to files, and the file-based tools are not offered.
+const ARGV   = process.argv.slice(2);
+const argOf  = (flag, dflt) => { const i = ARGV.indexOf(flag); return i >= 0 && ARGV[i + 1] != null ? ARGV[i + 1] : dflt; };
+const REMOTE = ARGV.includes('--http');
+const HTTP_PORT = Number(argOf('--port', process.env.PORT ?? 8000));
+const HTTP_HOST = argOf('--host', process.env.HOST ?? '127.0.0.1');
+const HTTP_PATH = '/mcp';
+// Largest request body accepted in HTTP mode (the CSV travels inside it).
+const HTTP_MAX_BODY = Math.round(Number(argOf('--max-body-mb', process.env.ENA_MCP_MAX_BODY_MB ?? 25)) * 1024 * 1024);
+if (ARGV.includes('--help') || ARGV.includes('-h')) {
+    process.stdout.write([
+        'Usage: qe-mcp-ena [--http [--port N] [--host H] [--max-body-mb N]]',
+        '',
+        '  (no flags)   MCP over stdio — what Claude Desktop, Claude Code and other local clients run.',
+        '  --http       MCP over streamable HTTP at /mcp, for hosting. Data must be passed inline',
+        '               (data_csv); nothing is written to disk; ena_profile, ena_tables, ena_lines and',
+        '               ena_export are not offered. Health check: GET /healthz.',
+        '  --port N     Port for --http (default: $PORT or 8000).',
+        '  --host H     Interface for --http (default: $HOST or 127.0.0.1; use 0.0.0.0 in a container).',
+        '  --max-body-mb N  Largest request body in MB (default: $ENA_MCP_MAX_BODY_MB or 25).',
+        '',
+    ].join('\n'));
+    process.exit(0);
+}
 import {
     CallToolRequestSchema,
     ListToolsRequestSchema,
@@ -37,13 +70,15 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import loadENA, { detectParams, isBinary } from '@qe-libs/rena-wasm';
 
-// Path to the qeviz UMD bundle (self-contained, no external deps)
+// qeviz: renderSVG() draws the static plot here, with no DOM; the UMD bundle
+// (self-contained, no external deps) is inlined into the interactive page.
+import { renderSVG as qevizRenderSVG } from '@qe-libs/qeviz';
 import { createRequire } from 'module';
 const _require = createRequire(import.meta.url);
 const QEVIZ_BUNDLE = _require.resolve('@qe-libs/qeviz');
 let _qevizJS = null;
 function qevizJS() {
-    // The bundle is inlined into pages and jsdom, so drop its source-map comment
+    // The bundle is inlined into pages, so drop its source-map comment
     // (the .map file is not next to the inlined copy).
     if (!_qevizJS) _qevizJS = readFileSync(QEVIZ_BUNDLE, 'utf8')
         .replace(/\n\/\/# sourceMappingURL=\S*\s*$/, '\n');
@@ -101,7 +136,12 @@ function dataFileText(dataPath) {
     return readFileSync(dataPath, 'utf8');
 }
 
+const REMOTE_NO_PATH =
+    'data_path is not available on a hosted server: it has no access to the user\'s files. ' +
+    'Pass the data inline as data_csv, after confirming with the user that it is de-identified.';
+
 function loadData(dataPath, dataCsv) {
+    if (dataPath && REMOTE) throw new Error(REMOTE_NO_PATH);
     if (dataPath)  return parseCSV(dataFileText(dataPath));
     if (dataCsv)   return parseCSV(dataCsv);
     throw new Error('Provide either data_path (path to a .csv or .xlsx file) or data_csv (raw CSV string).');
@@ -444,7 +484,7 @@ function detectColumns(rows) {
 // <qe-graph>), attrs (<qe-graph> attributes), edgePx, title }.
 
 // Group values and titles come from the data and from tool arguments; escape
-// them before they go into markup (renderSVG parses it with scripts enabled).
+// them before they go into the interactive page's markup.
 const escHtml = (v) => String(v).replace(/[&<>"']/g, ch =>
     ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
 
@@ -645,9 +685,7 @@ function vizSlug(result, args = {}) {
         .join('_');
 }
 
-// ── jsdom SVG renderer ────────────────────────────────────────────────────────
-
-import { JSDOM } from 'jsdom';
+// ── static SVG renderer ───────────────────────────────────────────────────────
 
 // PNG output (the inline image block and the png_plot file) prefers the native
 // @resvg/resvg-js, an OPTIONAL dependency: fastest, and it reads system fonts.
@@ -686,34 +724,27 @@ async function getResvg() {
 
 const SVG_SIZE = 600;
 
+// qeviz's headless renderSVG() draws the same <qe-graph> the interactive page
+// shows (same attributes, same layer children) as a standalone SVG string,
+// without a DOM: no browser, no timers. Anything qeviz logs while drawing goes
+// to stderr, since stdout is the stdio transport.
 async function renderSVG(plot) {
-    const dom = new JSDOM(
-        `<!DOCTYPE html><body><qe-visual id="vis"><qe-graph id="g" width="${SVG_SIZE}" height="${SVG_SIZE}"` +
-        `${attrString({ ...plot.attrs, 'edge-width': edgeWidth(plot.edgePx, SVG_SIZE) })}>${layerMarkup(plot.layers)}</qe-graph></qe-visual></body>`,
-        { runScripts: 'dangerously', pretendToBeVisual: true }
-    );
-    const { window } = dom;
-
-    window.Element.prototype.getBoundingClientRect = () =>
-        ({ x:0, y:0, width:SVG_SIZE, height:SVG_SIZE, top:0, left:0, right:SVG_SIZE, bottom:SVG_SIZE });
-    window.requestAnimationFrame = cb => setTimeout(cb, 0);
-
     const toStderr = (...a) => process.stderr.write(a.map(String).join(' ') + '\n');
-    window.console = { log: toStderr, info: toStderr, warn: toStderr, error: toStderr, debug: () => {} };
-
-    const s = window.document.createElement('script');
-    s.textContent = qevizJS();
-    window.document.head.appendChild(s);
-
-    window.document.getElementById('vis').setModelData(plot.data);
-    await new Promise(r => setTimeout(r, 200));
-
-    const svgEl = window.document.getElementById('g')?.svg_element;
-    if (!svgEl) return null;
+    const saved = { log: console.log, info: console.info, warn: console.warn, debug: console.debug };
+    Object.assign(console, { log: toStderr, info: toStderr, warn: toStderr, debug: () => {} });
+    let svgHtml;
+    try {
+        svgHtml = qevizRenderSVG(plot.data, {
+            width:  SVG_SIZE,
+            height: SVG_SIZE,
+            graph:  { ...plot.attrs, 'edge-width': edgeWidth(plot.edgePx, SVG_SIZE) },
+            layers: plot.layers,
+        });
+    } finally {
+        Object.assign(console, saved);
+    }
+    if (!svgHtml) return null;
 
-    // XML serialization: outerHTML (HTML rules) leaves '<' unescaped inside
-    // attribute values, which resvg rejects when a label contains one.
-    let svgHtml = new window.XMLSerializer().serializeToString(svgEl);
     // resvg requires the SVG namespace declaration to parse the document
     if (!svgHtml.includes('xmlns=')) {
         svgHtml = svgHtml.replace('<svg', '<svg xmlns="http://www.w3.org/2000/svg"');
@@ -981,7 +1012,11 @@ function optsLines(p, nUnits) {
     ];
 }
 
-function nextModelId() { return `m${++modelSeq}`; }
+// Hosted, the one process serves every client, so a model_id must not be
+// guessable: m1 from one conversation is not for another to plot.
+function nextModelId() {
+    return REMOTE ? `m${++modelSeq}-${randomBytes(6).toString('hex')}` : `m${++modelSeq}`;
+}
 
 // ── Web tool defaults ─────────────────────────────────────────────────────────
 
@@ -1587,7 +1622,7 @@ function toolInspect({ data_path, data_csv }) {
         nextStep = {
             tool: 'ena_fit',
             parameters: {
-                data_path:     data_path ?? '<save CSV to a path first>',
+                ...(REMOTE ? { data_csv: '<the same CSV text>' } : { data_path: data_path ?? '<save CSV to a path first>' }),
                 units:         bestUnit,
                 conversations: bestConvo,
                 codes:         codeCols,
@@ -1627,6 +1662,8 @@ function toolInspect({ data_path, data_csv }) {
 
     const privacyNote = isPrivacySafe
         ? 'PRIVACY SAFE — data was read from a local file path. No raw row data was sent to Claude; only this analysis result was transmitted.'
+        : REMOTE
+        ? 'HOSTED SERVER — the data was sent inline, processed in memory and not stored. It left the user\'s machine, so it must be de-identified; confirm that with the user if you have not.'
         : 'RAW DATA TRANSMITTED — data_csv was used, so row data passed through this conversation. For sensitive datasets, ask the user to save the file and provide data_path instead.';
 
     return {
@@ -2073,8 +2110,8 @@ async function toolCompareGroups(ena, params) {
 // ena_plot's display options → buildPlot's view.style (the web tool's Plot
 // Settings). Validated here so a bad colour or group fails with a message
 // instead of a blank plot.
-// qeviz resolves colour names through a canvas, which the SVG renderer
-// (jsdom) lacks, so names are turned into hex here: the CSS named colours.
+// Colour names are turned into hex here so the SVG and the interactive page
+// agree whatever resolves them: the CSS named colours.
 const CSS_NAMED = Object.fromEntries((
     'aliceblue:f0f8ff antiquewhite:faebd7 aqua:00ffff aquamarine:7fffd4 azure:f0ffff beige:f5f5dc ' +
     'bisque:ffe4c4 black:000000 blanchedalmond:ffebcd blue:0000ff blueviolet:8a2be2 brown:a52a2a ' +
@@ -2772,12 +2809,17 @@ const GUIDE_TOPICS = GUIDE?.sections.map(s => s.topic) ?? [];
 function toolGuide({ topic } = {}) {
     if (!GUIDE) throw new Error('The analysis guide is missing from this installation (skill/ena-analysis/SKILL.md).');
     const footer = `\n\n---\nTopics: ${GUIDE_TOPICS.join(', ')}`;
-    if (!topic) return GUIDE.text + footer;
+    const header = REMOTE
+        ? '> **Hosted server.** This server runs remotely, not on the user\'s machine. Where the guide says to pass ' +
+          'data_path, pass the data inline as data_csv instead, after the user confirms it is de-identified. ' +
+          'ena_profile, ena_tables, ena_lines and ena_export are not available here; plots come back inline.\n\n'
+        : '';
+    if (!topic) return header + GUIDE.text + footer;
     const t = String(topic).toLowerCase().trim();
     const hit = GUIDE.sections.find(s => s.topic === t)
         ?? GUIDE.sections.find(s => s.topic.includes(t.replace(/[^a-z0-9]+/g, '-')));
     if (!hit) throw new Error(`Unknown topic. Topics: ${GUIDE_TOPICS.join(', ')}`);
-    return hit.text + footer;
+    return header + hit.text + footer;
 }
 
 const TOOLS = [
@@ -3135,6 +3177,38 @@ const TOOLS = [
     },
 ];
 
+// Hosted: no user files to read or write, so the file tools go, data_path goes
+// from every schema, and the privacy wording changes from "keep it local" to
+// "send it de-identified".
+const REMOTE_HIDDEN_TOOLS = new Set(['ena_profile', 'ena_tables', 'ena_lines', 'ena_export']);
+const REMOTE_PRIVACY = 'PRIVACY (hosted server): the data is sent inline and processed in memory; it is not stored. ' +
+    'Before sending it, confirm with the user that it is de-identified. ';
+function remoteTools(tools) {
+    return tools.filter(t => !REMOTE_HIDDEN_TOOLS.has(t.name)).map(t => {
+        const { data_path, ...properties } = t.inputSchema.properties ?? {};
+        let description = t.description
+            .replace(/The ENA network plot is written to disk[^]*?Use these paths to show the plot; /,
+                     'The ENA network plot comes back as an inline image. Use it to show the plot; ')
+            .replace(/The ENA network plot is written to disk[^]*?is installed\./,
+                     'The ENA network plot comes back as an inline image (and the SVG as text).')
+            .replace(/The interactive HTML has its own controls[^.]*\. /, '')
+            .replace(/PRIVACY: .*?\.(?: (?=[A-Z])|$)/g, REMOTE_PRIVACY)
+            .replace(/ ?The WASM model runs entirely on the user's machine[^.]*\./, '')
+            .replace(/If the user has not yet indicated whether their data is sensitive, ask before using data_csv\. ?/, '')
+            .replace(/If they indicate sensitivity, use ena_profile instead \(no raw data transmitted\)\. ?/, '')
+            .trim();
+        const required = (t.inputSchema.required ?? []).filter(r => r !== 'data_path');
+        if (properties.data_csv && !description.includes(REMOTE_PRIVACY.trim()))
+            description = `${description} ${REMOTE_PRIVACY.trim()}`;
+        if (properties.data_csv) properties.data_csv = {
+            type: 'string',
+            description: 'The data as CSV text. The server has no access to the user\'s files; it processes this in memory and does not store it. Send only de-identified data.',
+        };
+        return { ...t, description, inputSchema: { ...t.inputSchema, properties, ...(required.length ? { required } : {}) } };
+    });
+}
+const OFFERED_TOOLS = REMOTE ? remoteTools(TOOLS) : TOOLS;
+
 // ── Server setup ──────────────────────────────────────────────────────────────
 
 const PKG = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
@@ -3175,7 +3249,23 @@ function withholdDataValues(msg, args) {
 
 // Sent to the client at connection; MCP clients (Claude, Codex, Gemini CLI,
 // Cursor, ...) pass it to the model, so the privacy rule reaches every one.
-const SERVER_INSTRUCTIONS = [
+const SERVER_INSTRUCTIONS = REMOTE ? [
+    'ENA / ONA / TMA analysis on a hosted server. The server does not run on the user\'s machine and cannot read their files.',
+    '',
+    'Data privacy — follow in every conversation:',
+    '- Data reaches these tools inline, as data_csv. It is processed in memory for the duration of the call and is not stored.',
+    '- Before the first analysis, tell the user that the data leaves their machine and must be de-identified: no names, e-mail addresses or identifying free text. Ask them to confirm before sending it.',
+    '- Results include unit labels (the values of the unit columns, often participant IDs) and group values. If those are identifying, tell the user before fitting so they can pseudonymize the data first.',
+    '- The guide may mention data_path, ena_profile, ena_tables, ena_lines or ena_export; those are for the locally installed server and are not available here.',
+    '',
+    'Results come only from these tools — follow in every conversation:',
+    '- Every ENA, ONA or TMA result shown to the user (accumulated networks, points, rotations, statistics, plots) must come from these tools. Do not compute any part of an ENA analysis yourself — in code, a notebook, R, Python or by hand — and do not draw ENA-style network plots of your own.',
+    '- If a tool fails, read its error, fix the call and retry, or tell the user what failed and stop. Never fill the gap with a substitute that looks like ENA, and never present estimated or illustrative numbers as results.',
+    '- If the user wants something these tools cannot do, say so, and suggest the locally installed server (https://qe-libs.org/mcp/qe-mcp-ena/), rENA in R or the ENA Web Tool, rather than improvising it.',
+    `- Results carry provenance ("${PKG.name} <version>"); anything without it did not come from this server.`,
+    '',
+    'Before the first analysis in a conversation, call ena_guide (no arguments) for the analysis workflow: triage, window, rotations, masking, ONA/TMA and reading the results. ena_guide with a topic returns one section.',
+].join('\n') : [
     'ENA / ONA / TMA analysis that runs locally on the user\'s machine.',
     '',
     'Data privacy — follow in every conversation:',
@@ -3231,10 +3321,19 @@ const PROMPTS = [
     },
 ];
 
-const server = new Server(
-    { name: 'ena', version: PKG.version },
-    { capabilities: { tools: {}, prompts: {} }, instructions: SERVER_INSTRUCTIONS }
-);
+// Handlers are collected, then attached to each Server instance: stdio has one
+// for the process, HTTP mode builds one per request (stateless, so any replica
+// can answer any request). The caches above are per process either way.
+const HANDLERS = [];
+const on = (schema, handler) => HANDLERS.push([schema, handler]);
+function buildServer() {
+    const server = new Server(
+        { name: 'ena', version: PKG.version },
+        { capabilities: { tools: {}, prompts: {} }, instructions: SERVER_INSTRUCTIONS }
+    );
+    for (const [schema, handler] of HANDLERS) server.setRequestHandler(schema, handler);
+    return server;
+}
 
 // ── rena-wasm API adapter ─────────────────────────────────────────────────────
 // rena-wasm ≥ the R-mirroring rewrite returns an R-style ENA set object
@@ -3322,15 +3421,16 @@ function getENA() {
     return enaPromise;
 }
 
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+on(ListToolsRequestSchema, async () => ({ tools: OFFERED_TOOLS }));
 
-server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-    prompts: PROMPTS.map(({ text, ...p }) => p),
+// The prompts take a data_path, so hosted there are none.
+on(ListPromptsRequestSchema, async () => ({
+    prompts: REMOTE ? [] : PROMPTS.map(({ text, ...p }) => p),
 }));
 
-server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+on(GetPromptRequestSchema, async (request) => {
     const { name, arguments: a = {} } = request.params;
-    const p = PROMPTS.find(x => x.name === name);
+    const p = REMOTE ? null : PROMPTS.find(x => x.name === name);
     if (!p) throw new Error(`Unknown prompt: ${name}`);
     for (const arg of p.arguments)
         if (arg.required && !a[arg.name]) throw new Error(`Missing argument: ${arg.name}`);
@@ -3340,9 +3440,12 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
     };
 });
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+on(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
+        if (REMOTE && REMOTE_HIDDEN_TOOLS.has(name))
+            throw new Error(`${name} is not available on a hosted server: it writes or reads files on the user's machine. ` +
+                'It is available in the locally installed server (https://qe-libs.org/mcp/qe-mcp-ena/).');
         // rena-wasm windows look backward only (= rENA's window.size.back); a
         // forward window would otherwise be silently ignored.
         if (Number(args?.window_forward) > 0)
@@ -3388,7 +3491,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 svg = await renderSVG(_plot);
                 if (svg) {
                     // SVG file — always available (pure JS/WASM), vector, embeddable.
-                    try { artifacts.svg_plot = writeVizFile(svg, slug, 'svg'); }
+                    // Hosted there is no disk the user can reach: the SVG rides
+                    // along as a text block instead, after the JSON.
+                    if (REMOTE) content.push({ type: 'text', text: svg });
+                    else 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
@@ -3401,11 +3507,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             data:     png.toString('base64'),
                             mimeType: 'image/png',
                         });
-                        try { artifacts.png_plot = writeVizFile(png, slug, 'png'); }
+                        if (!REMOTE) 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)';
+                    renderError = 'renderSVG returned null (qeviz produced no SVG)';
                 }
             } catch (e) {
                 renderError = e.message;
@@ -3418,12 +3524,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
 
             // Self-contained interactive HTML for clients that don't render inline images.
-            try {
+            if (!REMOTE) try {
                 const html = generateHTML(_plot, _plot.title ?? cleanResult.label ?? name);
                 artifacts.interactive_plot = writeVizFile(html, slug, 'html');
             } catch (e) {
                 process.stderr.write(`[ena-mcp] HTML write failed: ${e.message}\n`);
             }
+            if (REMOTE) artifacts.plot_note = 'Hosted server: the plot is the inline image above (PNG) and the SVG text block below; no files were written.';
 
             // Merge all artifact paths into the text block in one pass.
             const textBlock = content.find(c => c.type === 'text');
@@ -3445,5 +3552,54 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
 // ── Start ─────────────────────────────────────────────────────────────────────
 
-const transport = new StdioServerTransport();
-await server.connect(transport);
+if (!REMOTE) {
+    await buildServer().connect(new StdioServerTransport());
+} else {
+    // Streamable HTTP, stateless: every POST gets a fresh Server + transport
+    // and is answered in full, so no session state lives in the process and
+    // any replica can take any request. Model caches are per process (see
+    // README: one replica, or sticky sessions, keeps model_ids valid).
+    // Reads the body up to the cap; past it the rest is drained unread so the
+    // client gets the 413 instead of a dropped connection.
+    const readBody = (req) => new Promise((resolve, reject) => {
+        const chunks = []; let size = 0, tooLarge = Number(req.headers['content-length']) > HTTP_MAX_BODY;
+        req.on('data', (c) => {
+            size += c.length;
+            if (tooLarge || size > HTTP_MAX_BODY) { tooLarge = true; chunks.length = 0; }
+            else chunks.push(c);
+        });
+        req.on('end', () => tooLarge
+            ? reject(Object.assign(new Error(`request body too large (limit ${Math.round(HTTP_MAX_BODY / 1048576)} MB)`), { status: 413 }))
+            : resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+    const json = (res, status, body) => {
+        res.writeHead(status, { 'content-type': 'application/json' });
+        res.end(JSON.stringify(body));
+    };
+    const http = createHttpServer(async (req, res) => {
+        const url = new URL(req.url, `http://${req.headers.host ?? 'localhost'}`);
+        if (url.pathname === '/healthz') return json(res, 200, { ok: true, server: PKG.name, version: PKG.version });
+        if (url.pathname !== HTTP_PATH) return json(res, 404, { error: `MCP endpoint is ${HTTP_PATH}` });
+        try {
+            let parsedBody;
+            if (req.method === 'POST') {
+                const raw = await readBody(req);
+                try { parsedBody = JSON.parse(raw); }
+                catch { return json(res, 400, { jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' }, id: null }); }
+            }
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            res.on('close', () => transport.close());
+            const server = buildServer();
+            await server.connect(transport);
+            await transport.handleRequest(req, res, parsedBody);
+        } catch (e) {
+            process.stderr.write(`[ena-mcp] http: ${e.message}\n`);
+            if (!res.headersSent) json(res, e.status ?? 500, { error: e.status === 413 ? e.message : 'internal error' });
+            else res.end();
+        }
+    });
+    http.listen(HTTP_PORT, HTTP_HOST, () => {
+        process.stderr.write(`[ena-mcp] ${PKG.name} ${PKG.version} serving MCP over HTTP at http://${HTTP_HOST}:${HTTP_PORT}${HTTP_PATH} (health: /healthz)\n`);
+    });
+}

package/xlsx.js

@@ -1,7 +1,8 @@
 /**
  * xlsx.js — read the first worksheet of an .xlsx file as CSV text, as the ENA
  * Web Tool does for an uploaded .xlsx (rENA-webtool js/XlsxReader.js, ported
- * to Node: zlib instead of JSZip, jsdom's DOMParser instead of the browser's).
+ * to Node: zlib instead of JSZip, a small XML reader instead of the browser's
+ * DOMParser).
  *
  * Parity with the web tool, and so with R's openxlsx::read.xlsx(sheet = 1):
  *   - first sheet in tab order only; its first row is the header row
@@ -11,7 +12,6 @@
  */
 
 import { inflateRawSync } from 'zlib';
-import { JSDOM } from 'jsdom';
 
 // ── ZIP: the entries of an .xlsx (a ZIP of XML parts) ────────────────────────
 function unzip(buf) {
@@ -42,10 +42,61 @@ function unzip(buf) {
     return { file: (name) => files.get(name)?.() ?? null };
 }
 
-let _parser;
+// ── XML: the little of it that SpreadsheetML needs ───────────────────────────
+// Elements with getElementsByTagName (descendants, local name), getAttribute
+// (prefixed or not) and textContent — the subset the readers below use. No
+// namespaces, DTDs or entities beyond the five predefined and numeric ones.
+const XML_ENTITIES = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+const unescapeXml = (s) => s.indexOf('&') < 0 ? s : s.replace(/&(#x[0-9a-fA-F]+|#\d+|\w+);/g, (m, e) =>
+    e[0] === '#' ? String.fromCodePoint(e[1] === 'x' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10))
+                 : (XML_ENTITIES[e] ?? m));
+
+class XmlElement {
+    constructor(name, attrs) { this.name = name; this.attrs = attrs; this.children = []; }
+    get localName() { const i = this.name.indexOf(':'); return i < 0 ? this.name : this.name.slice(i + 1); }
+    getAttribute(name) {
+        if (name in this.attrs) return this.attrs[name];
+        const i = name.indexOf(':');                       // "r:id" also matches an unprefixed "id"
+        return i >= 0 && name.slice(i + 1) in this.attrs ? this.attrs[name.slice(i + 1)] : null;
+    }
+    getAttributeNS(ns, local) {
+        for (const k in this.attrs) if (k === local || k.endsWith(':' + local)) return this.attrs[k];
+        return null;
+    }
+    get textContent() {
+        let out = '';
+        for (const c of this.children) out += typeof c === 'string' ? c : c.textContent;
+        return out;
+    }
+    getElementsByTagName(local) {
+        const out = [];
+        const walk = (el) => { for (const c of el.children) if (typeof c !== 'string') { if (c.localName === local) out.push(c); walk(c); } };
+        walk(this);
+        return out;
+    }
+}
+
+const ATTR_RE = /([^\s=\/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
 function parseXml(buf) {
-    _parser ??= new (new JSDOM('').window.DOMParser)();
-    return _parser.parseFromString(buf.toString('utf8'), 'application/xml');
+    const xml = buf.toString('utf8');
+    const root = new XmlElement('#document', {});
+    const stack = [root];
+    const TAG_RE = /<(\/)?([^\s\/>!?]+)([^>]*?)(\/)?>|<!\[CDATA\[([\s\S]*?)\]\]>|<!--[\s\S]*?-->|<[!?][^>]*>/g;
+    let last = 0, m;
+    while ((m = TAG_RE.exec(xml))) {
+        const text = xml.slice(last, m.index);
+        if (text) stack[stack.length - 1].children.push(unescapeXml(text));
+        last = TAG_RE.lastIndex;
+        if (m[5] !== undefined) { stack[stack.length - 1].children.push(m[5]); continue; }   // CDATA
+        if (m[2] === undefined) continue;                                                     // comment, PI, doctype
+        if (m[1]) { if (stack.length > 1) stack.pop(); continue; }                            // closing tag
+        const attrs = {};
+        for (const a of m[3].matchAll(ATTR_RE)) attrs[a[1]] = unescapeXml(a[2] ?? a[3] ?? '');
+        const el = new XmlElement(m[2], attrs);
+        stack[stack.length - 1].children.push(el);
+        if (!m[4]) stack.push(el);
+    }
+    return root;
 }
 
 // "A1" / "BC12" → 0-based column. Column letters are base-26 (bijective).