@qe-mcp/ena 0.1.19 → 0.1.20

package/README.md

@@ -183,10 +183,17 @@ privacy promise, and it says so to the model. In `--http` mode:
   minutes after its last use (default 60), then it is forgotten.
   `ena_simplify` refits, so hosted it takes `data_csv` again and checks that
   it is the data the model was fitted on.
-- `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.
+- `ena_export` has nowhere to write, so it returns the ENA Web Tool project
+  ZIP inline, as a base64 resource in the result. The ZIP holds the data
+  file, which the server no longer has, so it takes `data_csv` again (checked
+  the same way) and keeps neither the data nor the ZIP afterwards. A client
+  that cannot save a file from a result asks for `format: "set"` instead: the
+  set file alone, which needs no data and sends none back; the summary says
+  how to pack it with the user's own data file. There is no download link,
+  not even a short-lived one, because that would mean keeping the data.
+- `ena_profile`, `ena_tables` and `ena_lines` 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

package/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.2",
   "name": "qe-mcp-ena",
   "display_name": "ENA — Epistemic Network Analysis",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "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.19",
+  "version": "0.1.20",
   "description": "Epistemic Network Analysis for Claude and other assistants — runs on your machine",
   "repository": {
     "type": "git",

package/server.js

@@ -56,7 +56,7 @@ if (ARGV.includes('--help') || ARGV.includes('-h')) {
         '  --http       MCP over streamable HTTP at /mcp, for hosting. Data must be passed inline',
         '               (data_csv) and is discarded after each call; only fitted models are kept, for',
         '               $ENA_MCP_MODEL_TTL_MIN minutes (default 60); nothing is written to disk; ena_profile,',
-        '               ena_tables, ena_lines and ena_export are not offered. Health check: GET /healthz.',
+        '               ena_tables and ena_lines are not offered; ena_export returns the ZIP inline. 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).',
@@ -860,6 +860,9 @@ const MAX_MODELS = 50;
 // model — points, networks, unit and group labels — is forgotten MODEL_TTL_MS
 // after its last use instead of waiting to be displaced.
 const KEEP_ROWS = !REMOTE;
+const EXPORT_HINT = REMOTE
+    ? 'or ena_export (with data_csv again, or format="set") for an ENA Web Tool project.'
+    : 'or ena_export to open the model in the ENA Web Tool.';
 let MODEL_TTL_MS = REMOTE ? Number(process.env.ENA_MCP_MODEL_TTL_MIN ?? 60) * 60_000 : 0;
 export function setModelTtl(minutes) { MODEL_TTL_MS = Number(minutes) * 60_000; }
 
@@ -1827,7 +1830,7 @@ async function toolFit(ena, params) {
         ...(tests ? ['', ...tests.lines] : []),
         '',
         `Use ena_plot with model_id="${model_id}" for additional views (group, unit, subtraction, comparison), ` +
-            `or ena_export to open the model in the ENA Web Tool.`,
+            EXPORT_HINT,
     ].join('\n');
 
     const result = {
@@ -2099,7 +2102,7 @@ async function toolCompareGroups(ena, params) {
         ),
         '',
         `Use ena_plot with model_id="${model_id}" for group, subtraction, comparison, or unit views, ` +
-            `or ena_export to open the model in the ENA Web Tool.`,
+            EXPORT_HINT,
     ].join('\n');
 
     const result = {
@@ -2638,7 +2641,7 @@ async function toolLines(ena, { model_id, connection, units, group, columns, max
     };
 }
 
-async function toolExport(ena, { model_id, set_name, out_path }) {
+async function toolExport(ena, { model_id, set_name, out_path, data_csv, format }) {
     const entry = modelGet(model_id);
     if (!entry)
         throw new Error(`Unknown model_id '${model_id}'. Fit the model first (ena_fit, ena_compare_groups or tma_fit).`);
@@ -2647,9 +2650,34 @@ async function toolExport(ena, { model_id, set_name, out_path }) {
         throw new Error(`Model ${model_id} can't be exported to the ENA Web Tool, which has no setting for: ${blockers.join('; ')}. ` +
             'Refit without these to export it.');
 
-    const p = entry.params;
+    let p = entry.params;
+    if (KEEP_ROWS) {
+        format = 'zip';
+    } else {
+        // The hosted server kept nothing but the model. The project ZIP holds
+        // the data file, so the data must come again (and be the same data);
+        // the set file alone needs no data unless the set stores excluded
+        // units or conversations, which are read from the rows.
+        format = format ?? 'zip';
+        if (format !== 'zip' && format !== 'set')
+            throw new Error('format must be "zip" (the project ZIP, which needs data_csv again) or "set" (the set file alone).');
+        if (data_csv) {
+            if (dataStamp({ data_csv }) !== entry._data)
+                throw new Error(`data_csv is not the data model ${model_id} was fitted on. Pass the same CSV, or fit a new model.`);
+            p = { ...p, data_csv };
+        } else if (format === 'zip') {
+            throw new Error('Hosted server: the data is not stored. Pass data_csv again (the CSV the model was fitted on) to build the ZIP, ' +
+                'or format="set" for the set file alone.');
+        }
+    }
     const unitCols = toArray(p.units);
     const warnings = [];
+    let _rows = null;
+    const fileRows = (why) => {
+        if (!p.data_path && p.data_csv == null)
+            throw new Error(`Hosted server: this set needs the rows (${why}). Pass data_csv again (the CSV the model was fitted on).`);
+        return _rows ??= loadRows({ data_path: p.data_path, data_csv: p.data_csv });
+    };
 
     // The web tool groups units by their first unit column; take that column's
     // groups (order, colours) for the stored set.
@@ -2660,8 +2688,7 @@ async function toolExport(ena, { model_id, set_name, out_path }) {
         if (entry.groupCol === groupCol) {
             groups = entry.web.groups.map(g => ({ name: g.name, color: g.color, secondaryColor: g.secondaryColor, showMean: g.showMean }));
         } else {
-            const rows = loadRows(p);
-            groups = web.groupOrder(rows, groupCol).map((name, i) => ({ name, ...web.groupStyle(i) }));
+            groups = web.groupOrder(fileRows(`the ${groupCol} groups`), groupCol).map((name, i) => ({ name, ...web.groupStyle(i) }));
             if (entry.groupCol)
                 warnings.push(`The web tool groups units by ${groupCol}, so its plots show ${groupCol} groups, not ${entry.groupCol}.`);
         }
@@ -2676,9 +2703,6 @@ async function toolExport(ena, { model_id, set_name, out_path }) {
 
     // The web tool's project holds a CSV; an .xlsx goes in as its first sheet.
     const csvName = p.data_path ? basename(p.data_path).replace(/\.xlsx$/i, '.csv') : 'data.csv';
-    const csv = p.data_path
-        ? (isXlsx(p.data_path) ? Buffer.from(dataFileText(p.data_path), 'utf8') : readFileSync(p.data_path))
-        : Buffer.from(p.data_csv ?? '', 'utf8');
     const setName = safeFileName(set_name ??
         (plotted.secondary ? `${plotted.primary} vs ${plotted.secondary}` : `ENA model ${model_id}`));
 
@@ -2687,7 +2711,6 @@ async function toolExport(ena, { model_id, set_name, out_path }) {
     // Built from the whole file: the web tool applies exclude_conversations
     // and order_by itself (WasmWrapper._modelRowIndices), on the data file the
     // ZIP carries unchanged.
-    const fileRows = loadRows({ data_path: p.data_path, data_csv: p.data_csv });
     const exclConvos = toArray(p.exclude_conversations).map(e => String(e).split('__').join('::'));
     let unitTree = null, excluded = 0;
     if (p.units_used?.length || exclConvos.length) {
@@ -2696,7 +2719,7 @@ async function toolExport(ena, { model_id, set_name, out_path }) {
         // rebuilds the conversation tree, which drops its include flags.
         const used = p.units_used?.length ? new Set(p.units_used.map(String)) : null;
         const seen = new Map();
-        for (const r of fileRows) {
+        for (const r of fileRows('excluded units')) {
             const values = unitCols.map(c => String(r[c]));
             const key = values.join('__');
             if (!seen.has(key)) seen.set(key, { values, include: used ? used.has(key) : true });
@@ -2709,7 +2732,7 @@ async function toolExport(ena, { model_id, set_name, out_path }) {
         const convoCols = toArray(p.conversations);
         const out = new Set(exclConvos);
         const seen = new Map();
-        for (const r of fileRows) {
+        for (const r of fileRows('excluded conversations')) {
             const values = convoCols.map(c => String(r[c]));
             const key = values.join('::');
             if (!seen.has(key)) seen.set(key, { values, include: !out.has(key) });
@@ -2733,19 +2756,6 @@ async function toolExport(ena, { model_id, set_name, out_path }) {
         source: { tool: PKG.name, version: PKG.version, model_id, exported: new Date().toISOString() },
     });
 
-    const zipBuf = web.zip([
-        { name: csvName, data: csv },
-        { name: 'Folder/' },
-        { name: `Folder/${setName}.json`, data: JSON.stringify(set, null, 2) },
-    ]);
-
-    let target = out_path
-        ? (extname(out_path).toLowerCase() === '.zip' ? out_path : join(out_path, `${setName}.zip`))
-        : join(p.data_path ? dirname(p.data_path) : VIZ_DIR, `${setName}.zip`);
-    target = freePath(target);
-    mkdirSync(dirname(target), { recursive: true });
-    writeFileSync(target, zipBuf);
-
     const rot = set.settings.model;
     const settings = {
         units: unitCols, conversations: toArray(p.conversations), codes: entry.codes,
@@ -2760,14 +2770,82 @@ async function toolExport(ena, { model_id, set_name, out_path }) {
         ...(p.order_by && { order_by: p.order_by }),
         ...(toArray(p.mask_connections).length && { masked_connections: toArray(p.mask_connections) }),
     };
+    const howToOpen = [
+        'To open it: start a local session in the ENA Web Tool ("Run Offline"), click Import in the Sets panel,',
+        `choose the ZIP, then open Folder › ${setName}. (Project import works in local sessions only.)`,
+    ];
+
+    if (format === 'set') {
+        // Hosted, without the data: the set file alone. The user packs the
+        // project themselves, so their data never has to come back here.
+        return {
+            set_name: setName,
+            data_file: csvName,
+            set_file: `Folder/${setName}.json`,
+            set,
+            settings,
+            warnings,
+            privacy_note: 'Hosted server: this is the set file only — settings, groups and labels, no rows. Nothing was stored.',
+            summary: [
+                `Set file for model ${model_id} (ENA Web Tool), without the data.`,
+                `  Set: Folder / ${setName}   Opens with: ${settings.opens_with}`,
+                ...warnings.map(w => `  Note: ${w}`),
+                '',
+                'To make the project ZIP: save the "set" field as JSON at Folder/' + setName + '.json, put the data file',
+                `the model was fitted on beside it as ${csvName} (that exact name), and zip the two —`,
+                `the ZIP holds ${csvName} and Folder/${setName}.json.`,
+                ...howToOpen,
+            ].join('\n'),
+        };
+    }
+
+    const csv = p.data_path
+        ? (isXlsx(p.data_path) ? Buffer.from(dataFileText(p.data_path), 'utf8') : readFileSync(p.data_path))
+        : Buffer.from(p.data_csv ?? '', 'utf8');
+    const zipBuf = web.zip([
+        { name: csvName, data: csv },
+        { name: 'Folder/' },
+        { name: `Folder/${setName}.json`, data: JSON.stringify(set, null, 2) },
+    ]);
+
+    if (!KEEP_ROWS) {
+        // Hosted: nowhere to write, so the ZIP rides along with the result as
+        // an embedded resource (base64). Nothing of it stays on the server.
+        return {
+            _zip: { name: `${setName}.zip`, data: zipBuf },
+            zip_file: `${setName}.zip`,
+            zip_bytes: zipBuf.length,
+            set_name: setName,
+            data_file: csvName,
+            settings,
+            warnings,
+            privacy_note: 'Hosted server: the ZIP holds the data sent with this call. The server kept neither the data nor the ZIP.',
+            summary: [
+                `Exported model ${model_id} as an ENA Web Tool project ZIP: ${setName}.zip (${zipBuf.length} bytes), ` +
+                    'attached to this result as a base64 resource (application/zip). Save it as a .zip file.',
+                `  Set: Folder / ${setName}   Data: ${csvName}`,
+                `  Opens with: ${settings.opens_with}`,
+                ...warnings.map(w => `  Note: ${w}`),
+                '',
+                ...howToOpen,
+            ].join('\n'),
+        };
+    }
+
+    let target = out_path
+        ? (extname(out_path).toLowerCase() === '.zip' ? out_path : join(out_path, `${setName}.zip`))
+        : join(p.data_path ? dirname(p.data_path) : VIZ_DIR, `${setName}.zip`);
+    target = freePath(target);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, zipBuf);
+
     const summary = [
         `Exported model ${model_id} as an ENA Web Tool project: ${target}`,
         `  Set: Folder / ${setName}   Data: ${csvName}`,
         `  Opens with: ${settings.opens_with}`,
         ...warnings.map(w => `  Note: ${w}`),
         '',
-        'To open it: start a local session in the ENA Web Tool ("Run Offline"), click Import in the Sets panel,',
-        `choose the ZIP, then open Folder › ${setName}. (Project import works in local sessions only.)`,
+        ...howToOpen,
     ].join('\n');
 
     return {
@@ -2855,7 +2933,8 @@ function toolGuide({ topic } = {}) {
     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'
+          'ena_profile, ena_tables and ena_lines are not available here; plots come back inline, and ena_export returns ' +
+          'the project ZIP inline (with data_csv again) or the set file alone (format="set").\n\n'
         : '';
     if (!topic) return header + GUIDE.text + footer;
     const t = String(topic).toLowerCase().trim();
@@ -3208,13 +3287,16 @@ const TOOLS = [
             'it rebuilds the same model and opens on the same comparison plot. ' +
             'Excluded units (units_used) are stored as excluded in the web tool\'s Units tab. Models the web tool has no setting for (transmodal or time windows, a GMR on x_var, rotations by a column other than the first unit column, ' +
             'center_align_to_origin=false) are refused with the reason. ' +
-            'PRIVACY: the ZIP contains the data file. It is written locally (by default next to the data file, never overwriting one) and no rows are sent to Claude.',
+            'PRIVACY: the ZIP contains the data file. It is written locally (by default next to the data file, never overwriting one) and no rows are sent to Claude. ' +
+            'HOSTED: there is no disk; the ZIP comes back inline, built from data_csv sent again with the call, or format="set" returns the set file alone for the user to pack with their own data file.',
         inputSchema: {
             type: 'object',
             properties: {
                 model_id: { type: 'string', description: 'model_id of the model to export' },
                 set_name: { type: 'string', description: 'Name of the set in the web tool (default: "<group 1> vs <group 2>", or "ENA model <id>")' },
-                out_path: { type: 'string', description: 'Where to write: a .zip path, or a folder. Default: the data file\'s folder, as "<set name>.zip" (a number is added rather than overwrite).' },
+                out_path: { type: 'string', description: 'Where to write: a .zip path, or a folder. Default: the data file\'s folder, as "<set name>.zip" (a number is added rather than overwrite).', _localOnly: true },
+                format:   { type: 'string', enum: ['zip', 'set'], description: 'Hosted server only. "zip" (default): the project ZIP, returned inline as a base64 resource; needs data_csv again. "set": the set file alone (no data needed, nothing sent back but settings); the user packs it with their own data file as the summary says. Locally, omit.', _hostedOnly: true },
+                data_csv: { type: 'string', description: 'Hosted server only: the CSV the model was fitted on, again (the server does not store it). Required for format "zip". Locally, omit.', _hostedOnly: true },
             },
             required: ['model_id'],
         },
@@ -3224,13 +3306,14 @@ 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_HIDDEN_TOOLS = new Set(['ena_profile', 'ena_tables', 'ena_lines']);
 const REMOTE_PRIVACY = 'PRIVACY (hosted server): the data is sent inline and processed in memory; it is discarded when the call returns, and only the fitted model is kept, for a limited time. ' +
     '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 ?? {};
+        const { data_path, ...properties } = Object.fromEntries(Object.entries(t.inputSchema.properties ?? {}).filter(([, v]) => !v._localOnly));
         let description = t.description
+            .replace(/ ?It is written locally[^.]*\. HOSTED: /, ' Hosted: ')
             .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\./,
@@ -3241,6 +3324,7 @@ function remoteTools(tools) {
             .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();
+        for (const [k, v] of Object.entries(properties)) if (v._hostedOnly) { const { _hostedOnly, ...d } = v; properties[k] = d; }
         const required = (t.inputSchema.required ?? []).filter(r => r !== 'data_path');
         if (properties.data_csv && !description.includes(REMOTE_PRIVACY.trim()))
             description = `${description} ${REMOTE_PRIVACY.trim()}`;
@@ -3254,8 +3338,10 @@ function remoteTools(tools) {
 }
 function localTools(tools) {
     return tools.map(t => {
-        const properties = Object.fromEntries(Object.entries(t.inputSchema.properties ?? {}).filter(([, v]) => !v._hostedOnly));
-        return { ...t, inputSchema: { ...t.inputSchema, properties } };
+        const properties = Object.fromEntries(Object.entries(t.inputSchema.properties ?? {}).filter(([, v]) => !v._hostedOnly)
+            .map(([k, { _localOnly, ...v }]) => [k, v]));
+        const description = t.description.replace(/ HOSTED: .*$/, '');
+        return { ...t, description, inputSchema: { ...t.inputSchema, properties } };
     });
 }
 const OFFERED_TOOLS = REMOTE ? remoteTools(TOOLS) : localTools(TOOLS);
@@ -3302,10 +3388,11 @@ const serverInstructions = () => REMOTE ? [
     '',
     'Data privacy — follow in every conversation:',
     '- Data reaches these tools inline, as data_csv. It is parsed in memory for the call and discarded when the call returns: the server keeps no rows and no CSV text, in memory or on disk.',
-    `- What a model_id refers to — the fitted model: points, networks, unit labels and group values, never the rows — stays in memory for ${Math.round(MODEL_TTL_MS / 60_000)} minutes after its last use, then is forgotten. ena_simplify refits, so it takes data_csv again.`,
+    `- What a model_id refers to — the fitted model: points, networks, unit labels and group values, never the rows — stays in memory for ${Math.round(MODEL_TTL_MS / 60_000)} minutes after its last use, then is forgotten. ena_simplify refits and ena_export packs the data file, so they take data_csv again; ena_export with format="set" takes none.`,
     '- 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.',
+    '- The guide may mention data_path, ena_profile, ena_tables or ena_lines; those are for the locally installed server and are not available here.',
+    '- ena_export returns the ENA Web Tool project ZIP inline (a base64 resource) when it gets data_csv again. If the client cannot save a file from a result, use format="set" and give the user the set file and the packing steps from the summary; their data file never has to come back 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.',
@@ -3525,10 +3612,14 @@ on(CallToolRequestSchema, async (request) => {
         }
 
         // Extract viz fields before stringifying so they never appear in the text block.
-        const { _plot, ...cleanResult } = result;
+        const { _plot, _zip, ...cleanResult } = result;
 
         cleanResult.provenance = PROVENANCE;
         const content = [{ type: 'text', text: JSON.stringify(cleanResult, null, 2) }];
+        if (_zip) content.push({
+            type: 'resource',
+            resource: { uri: `ena://export/${encodeURIComponent(_zip.name)}`, mimeType: 'application/zip', blob: _zip.data.toString('base64') },
+        });
 
         if (_plot) {
             const slug = vizSlug(cleanResult, args) || name;