@qe-mcp/server-ena 0.1.1

package/skill/ena-analysis/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ena-analysis
+description: >
+  Run Epistemic Network Analysis (ENA) on tabular coded data using the
+  @qe-mcp/server-ena connector. Use whenever the user references tabular data
+  with binary presence/absence codes and asks for analysis, exploration,
+  co-occurrence patterns, or group comparison — especially discourse data,
+  behavioral coding, learning analytics, or clinical observation data.
+  Includes a privacy gate for sensitive datasets: raw data can stay entirely
+  on the user's machine.
+---
+
+# ENA Analysis
+
+Epistemic Network Analysis models patterns of co-occurrence between coded
+events (discourse moves, behaviors, features) within conversations, projecting
+each unit of analysis into a low-dimensional space where distances are
+interpretable. It reveals structural differences that summary statistics and
+regression miss.
+
+This skill drives the **ena** MCP connector (`@qe-mcp/server-ena`). All model
+computation runs locally on the user's machine via WebAssembly — only results
+(node positions, plots, summary statistics) are returned to Claude.
+
+## Privacy gate — always ask first
+
+Before calling any ENA tool on new data, ask:
+
+> "Is this data sensitive or confidential? If so, give me the file path
+> instead of pasting the data — raw data stays on your machine when you use
+> a file path."
+
+If the data is sensitive (or the user hasn't answered yet):
+
+1. Call `ena_profile` with only `data_path`. It returns column names, unique
+   counts, and binary detection — **no raw row data is ever transmitted**.
+2. Use the profile to determine parameters (units, conversations, codes).
+3. Call `ena_fit` / `ena_compare_groups` with `data_path`. Only model results
+   reach the conversation.
+
+Note: unit labels (values from the unit column, e.g. participant IDs) appear
+in model results. If those are themselves sensitive, warn the user before
+fitting.
+
+If the data is not sensitive, or is toy/demo data, proceed with `ena_inspect`
+directly. Prefer `data_path` over `data_csv` in all cases; use `data_csv`
+only for small pasted samples.
+
+## When ENA fits the data
+
+- Rows are utterances, events, or observations
+- Columns include binary (0/1) presence/absence codes
+- A column identifies who produced each row (unit of analysis)
+- A column groups rows into episodes or conversations
+- Optionally: two or more conditions/groups to compare
+
+## Workflow
+
+1. **Triage** — `ena_inspect` (or `ena_profile` for sensitive data). Returns
+   `ena_recommended`, suggested codes/units/conversations, and a pre-filled
+   `next_step` call. If `ena_recommended` is true, propose ENA as the primary
+   analysis and briefly explain what it will reveal.
+2. **Fit** — `ena_fit` for a single model, or `ena_compare_groups` when two
+   groups exist. Both return a `model_id` and an inline network plot.
+   Do not generate your own visualization — the plot comes back as an image.
+3. **Explore** — `ena_plot` with the cached `model_id` renders additional
+   views without refitting:
+   - `all` — all units
+   - `group` — one group's mean network (`group_value`)
+   - `comparison` — two group networks overlaid (`group1`, `group2`)
+   - `subtraction` — difference network (`group1`, `group2`)
+   - `unit` — a single unit's network (`unit_label`)
+4. **Interpret** — strong connections indicate codes that co-occur within
+   the stanza window; in subtraction plots, edge color/direction shows which
+   group each connection favors. Node positions are fixed across views of the
+   same model, so plots are directly comparable.
+
+Each fit/plot response also includes `interactive_plot` — a local HTML file
+path with the interactive visualization the user can open in a browser.
+
+Repeated calls with identical parameters return the cached model instantly,
+so iterating on views is cheap.

package/test-mcp.mjs

@@ -0,0 +1,189 @@
+/**
+ * test-mcp.mjs — drive the MCP server over newline-delimited JSON-RPC.
+ *
+ * Usage:
+ *   node test-mcp.mjs
+ *   node test-mcp.mjs /path/to/data.csv UnitCol ConvoCol Code1 Code2 ...
+ *
+ * PNG images are saved to /tmp/ena-test-N.png and opened automatically.
+ */
+
+import { spawn }        from 'child_process';
+import { writeFileSync } from 'fs';
+import { createInterface } from 'readline';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+
+// ── configure ─────────────────────────────────────────────────────────────────
+
+const DATA_PATH = process.argv[2] ?? null;
+// UNIT_COL/CONVO_COL accept a single string or comma-separated list for compound columns
+const UNIT_COL  = process.argv[3] ?? 'ENA_UNIT';
+const CONVO_COL = process.argv[4] ?? 'Condition';
+const CODES     = process.argv.slice(5).length
+    ? process.argv.slice(5)
+    : ['CodeA', 'CodeB', 'CodeC'];
+
+// For rs.data.new.csv group comparison:
+//   units=['UserName','Condition']  conversations='GameDay'  group_col='Condition'
+//   group1='FirstGame'  group2='SecondGame'
+const GROUP_COL = DATA_PATH ? 'Condition'  : null;
+const GROUP1    = DATA_PATH ? 'FirstGame'  : null;
+const GROUP2    = DATA_PATH ? 'SecondGame' : null;
+
+// Compound units: each UserName×Condition pair is a separate unit
+const UNIT_COLS = DATA_PATH ? ['UserName', 'Condition'] : UNIT_COL;
+const CONVO_COLS = DATA_PATH ? 'GameDay' : CONVO_COL;
+
+const INLINE_CSV = `ENA_UNIT,Condition,CodeA,CodeB,CodeC
+u1,A,1,0,1
+u1,A,0,1,1
+u2,A,1,1,0
+u2,A,0,0,1
+u3,B,1,1,0
+u3,B,1,0,1
+u4,B,0,1,1
+u4,B,1,1,0`;
+
+// ── transport (newline-delimited JSON, as used by SDK v1.4) ───────────────────
+
+const proc = spawn('node', [join(DIR, 'server.js')], {
+    stdio: ['pipe', 'pipe', 'inherit'],
+});
+
+let _seq = 0;
+const _pending = new Map();
+
+const rl = createInterface({ input: proc.stdout, crlfDelay: Infinity });
+rl.on('line', line => {
+    if (!line.trim()) return;
+    let msg;
+    try { msg = JSON.parse(line); } catch { return; }
+    const cb = _pending.get(msg.id);
+    if (cb) { _pending.delete(msg.id); cb(msg); }
+});
+
+proc.on('close', () => {
+    for (const cb of _pending.values()) cb({ error: { message: 'server closed' } });
+});
+
+function rpc(method, params) {
+    const id = ++_seq;
+    return new Promise(resolve => {
+        _pending.set(id, resolve);
+        proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+    });
+}
+
+// ── result handler ────────────────────────────────────────────────────────────
+
+let imgCount = 0;
+
+function handleResult(label, msg) {
+    if (msg.error) {
+        console.log(`[${label}]  ✗  ${msg.error.message ?? JSON.stringify(msg.error)}`);
+        return null;
+    }
+    const content = msg.result?.content ?? [];
+    let parsed = null;
+    for (const block of content) {
+        if (block.type === 'image') {
+            const path = `/tmp/ena-test-${++imgCount}.png`;
+            writeFileSync(path, Buffer.from(block.data, 'base64'));
+            console.log(`[${label}]  ✓  image → ${path}`);
+        }
+        if (block.type === 'text') {
+            try { parsed = JSON.parse(block.text); } catch { parsed = block.text; }
+            if (parsed?._render_error)    console.log(`            render error: ${parsed._render_error}`);
+            if (parsed?.interactive_plot) console.log(`            html → ${parsed.interactive_plot}`);
+        }
+    }
+    return parsed;
+}
+
+// ── test sequence ─────────────────────────────────────────────────────────────
+
+async function run() {
+    // Handshake
+    const initMsg = await rpc('initialize', {
+        protocolVersion: '2024-11-05',
+        capabilities:    {},
+        clientInfo:      { name: 'test-mcp', version: '1.0' },
+    });
+    if (initMsg.error) throw new Error('initialize failed: ' + initMsg.error.message);
+    // Required: send initialized notification (no response)
+    proc.stdin.write(JSON.stringify({ jsonrpc:'2.0', method:'notifications/initialized' }) + '\n');
+
+    // List tools
+    const listMsg = await rpc('tools/list', {});
+    const tools   = listMsg.result?.tools ?? [];
+    console.log(`tools: ${tools.map(t => t.name).join(', ')}\n`);
+
+    const data = DATA_PATH ? { data_path: DATA_PATH } : { data_csv: INLINE_CSV };
+
+    // ena_profile (privacy-safe metadata only — only works with data_path)
+    if (DATA_PATH) {
+        const profile = handleResult('ena_profile',
+            await rpc('tools/call', { name: 'ena_profile', arguments: { data_path: DATA_PATH } }));
+        if (profile) {
+            console.log(`            ${profile.privacy_note}`);
+            console.log(`            binary cols: ${profile.binary_columns?.join(', ')}`);
+        }
+    }
+
+    // ena_inspect
+    const inspect = handleResult('ena_inspect',
+        await rpc('tools/call', { name: 'ena_inspect', arguments: data }));
+    if (inspect) {
+        console.log(`            recommended=${inspect.ena_recommended}  codes: ${inspect.suggested_codes?.join(', ')}`);
+        if (inspect.privacy_note) console.log(`            ${inspect.privacy_note}`);
+    }
+
+    // ena_fit
+    const fitArgs = {
+        ...data,
+        units: UNIT_COLS, conversations: CONVO_COLS, codes: CODES,
+        window_size: 4, binary: true, dims: 2, rotation: 'svd',
+        ...(GROUP_COL ? { group_col: GROUP_COL } : {}),
+    };
+    const fit = handleResult('ena_fit',
+        await rpc('tools/call', { name: 'ena_fit', arguments: fitArgs }));
+    if (!fit) { proc.kill(); return; }
+    console.log(`            model_id=${fit.model_id}  units=${fit.n_units}  connections=${fit.n_connections}`);
+
+    const modelId = fit.model_id;
+
+    // ena_plot — all units
+    handleResult('ena_plot(all)',
+        await rpc('tools/call', { name: 'ena_plot', arguments: { model_id: modelId, type: 'all' } }));
+
+    // ena_plot — first unit
+    const firstUnit = fit.units?.[0];
+    if (firstUnit) {
+        handleResult(`ena_plot(unit=${firstUnit})`,
+            await rpc('tools/call', { name: 'ena_plot', arguments: { model_id: modelId, type: 'unit', unit_label: firstUnit } }));
+    }
+
+    // ena_compare_groups + subtraction (if GROUP_COL is set)
+    if (GROUP_COL && GROUP1 && GROUP2) {
+        const cmpArgs = { ...fitArgs, rotation: undefined, group_col: GROUP_COL, group1_value: GROUP1, group2_value: GROUP2 };
+        delete cmpArgs.rotation;
+        const cmp = handleResult('ena_compare_groups',
+            await rpc('tools/call', { name: 'ena_compare_groups', arguments: cmpArgs }));
+        if (cmp) {
+            console.log(`            model_id=${cmp.model_id}  g1=${JSON.stringify(cmp.group1_mean)}  g2=${JSON.stringify(cmp.group2_mean)}`);
+            handleResult('ena_plot(subtraction)',
+                await rpc('tools/call', { name: 'ena_plot', arguments: { model_id: cmp.model_id, type: 'subtraction', group1: GROUP1, group2: GROUP2 } }));
+            handleResult('ena_plot(comparison)',
+                await rpc('tools/call', { name: 'ena_plot', arguments: { model_id: cmp.model_id, type: 'comparison', group1: GROUP1, group2: GROUP2 } }));
+        }
+    }
+
+    proc.stdin.end();
+    console.log(`\ndone — ${imgCount} image(s) saved`);
+    if (imgCount) console.log('open:  open /tmp/ena-test-*.png');
+}
+
+run().catch(err => { console.error(err.message); proc.kill(); });

package/test-render.mjs

@@ -0,0 +1,93 @@
+/**
+ * Smoke test: load WASM, fit a model, render to PNG.
+ * Run with: node test-render.mjs
+ */
+import loadENA from '@qe-libs/rena-wasm';
+import { readFileSync, writeFileSync } from 'fs';
+import { createRequire } from 'module';
+import { JSDOM } from 'jsdom';
+import { Resvg } from '@resvg/resvg-js';
+
+const _require = createRequire(import.meta.url);
+const QEVIZ_BUNDLE = _require.resolve('@qe-libs/qeviz');
+const qevizJS = () => readFileSync(QEVIZ_BUNDLE, 'utf8');
+const SVG_SIZE = 600;
+
+// Minimal synthetic dataset
+const rows = [
+    { unit: 'A', convo: 'c1', X: '1', Y: '0', Z: '1' },
+    { unit: 'A', convo: 'c1', X: '0', Y: '1', Z: '1' },
+    { unit: 'B', convo: 'c1', X: '1', Y: '1', Z: '0' },
+    { unit: 'B', convo: 'c1', X: '0', Y: '0', Z: '1' },
+    { unit: 'C', convo: 'c2', X: '1', Y: '1', Z: '0' },
+    { unit: 'C', convo: 'c2', X: '1', Y: '0', Z: '1' },
+];
+const codes = ['X', 'Y', 'Z'];
+
+console.log('1. Loading WASM...');
+const ena = await loadENA();
+console.log('   OK');
+
+console.log('2. Fitting model...');
+const model = ena.fit(rows, {
+    codes,
+    units: ['unit'],
+    conversations: ['convo'],
+    window: 4,
+    binary: true,
+    dims: 2,
+    rotation: 'svd',
+});
+console.log(`   OK — ${model.nUnits} units, ${model.nConnections} connections`);
+console.log(`   centroids type: ${model.centroids?.constructor?.name}`);
+console.log(`   positions type: ${model.positions?.constructor?.name}`);
+console.log(`   networks type:  ${model.networks?.constructor?.name}`);
+
+console.log('3. Building vizData...');
+const edgeColName = (n) => n.replace(' & ', '.');
+const modelData = {
+    directed: false, updated: Date.now(),
+    id_col: 'ENA_UNIT', node_id_col: 'code', x_col: 'x', y_col: 'y',
+    nodes: {
+        data: codes.map((code, i) => ({ code, x: model.positions[i*2], y: model.positions[i*2+1] })),
+        types: { code: 'character', x: 'numeric', y: 'numeric' },
+    },
+    edges: {
+        data: model.unitLabels.map((lbl, i) => {
+            const row = { ENA_UNIT: lbl };
+            model.connectionNames.forEach((n, j) => { row[edgeColName(n)] = model.networks[i * model.nConnections + j]; });
+            return row;
+        }),
+        types: Object.fromEntries([['ENA_UNIT','character'], ...model.connectionNames.map(n => [edgeColName(n),'numeric'])]),
+    },
+    points: {
+        data: model.unitLabels.map((lbl, i) => ({ ENA_UNIT: lbl, x: model.centroids[i*2], y: model.centroids[i*2+1] })),
+        types: { ENA_UNIT: 'character', x: 'numeric', y: 'numeric' },
+    },
+};
+console.log('   OK');
+
+console.log('4. Rendering SVG via jsdom...');
+const dom = new JSDOM(
+    `<!DOCTYPE html><body><qe-visual id="vis"><qe-graph id="g" width="${SVG_SIZE}" height="${SVG_SIZE}" label-nodes="on"><qe-points label="auto"></qe-points></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);
+window.console = { log: ()=>{}, info: ()=>{}, warn: ()=>{}, error: ()=>{}, debug: ()=>{} };
+const s = window.document.createElement('script');
+s.textContent = qevizJS();
+window.document.head.appendChild(s);
+window.document.getElementById('vis').setModelData(modelData);
+await new Promise(r => setTimeout(r, 300));
+const svg = window.document.getElementById('g')?.svg_element?.outerHTML ?? null;
+if (!svg) { console.error('   FAIL — svg_element is null'); process.exit(1); }
+console.log(`   OK — SVG ${svg.length} bytes`);
+
+console.log('5. Rasterizing to PNG via resvg...');
+const png = new Resvg(svg, { width: SVG_SIZE, height: SVG_SIZE }).render().asPng();
+writeFileSync('/tmp/ena-smoke.png', png);
+console.log(`   OK — PNG ${png.length} bytes → /tmp/ena-smoke.png`);
+console.log('\nAll steps passed. Open /tmp/ena-smoke.png to check the visual.');