@qe-mcp/server-ena 0.1.5 → 0.1.7

package/README.md

@@ -30,7 +30,24 @@ Gives Claude a set of ENA tools that run **locally on your machine**. The WASM m
 
 ## Installation
 
-The package is published to the public npm registry — no registry configuration needed.
+### Recommended — one-click desktop extension (`.mcpb`)
+
+The easiest install, no terminal or config files. Download `server-ena.mcpb`
+from the [releases](https://qe-libs.org/mcp/qe-mcp-server-ena/), then in
+Claude Desktop go to **Settings → Extensions** and drag the file in (or
+double-click it). Click Install and restart. Node.js ships inside Claude
+Desktop, so nothing else is required.
+
+The bundle is pure JS/WASM and cross-platform. It produces SVG (`svg_plot`)
+and interactive HTML (`interactive_plot`) plots; inline PNG rendering is
+omitted from the bundle (it requires a native module) — open the SVG or HTML
+to view the network.
+
+To build the bundle yourself: `bash scripts/build-mcpb.sh` → `dist/server-ena.mcpb`.
+
+---
+
+The package is also published to the public npm registry — no registry configuration needed.
 
 ### Option A — npx (no install needed)
 

package/manifest.json

@@ -0,0 +1,60 @@
+{
+  "manifest_version": "0.2",
+  "name": "server-ena",
+  "display_name": "ENA — Epistemic Network Analysis",
+  "version": "0.1.6",
+  "description": "Epistemic Network Analysis on tabular coded data. Runs entirely on your machine — data never leaves your computer.",
+  "long_description": "Model patterns of co-occurrence between coded events (discourse moves, behaviors, features) within conversations. The full ENA pipeline — accumulate, normalize, rotate, project, node positions — runs locally in WebAssembly; only results and plots are returned. Provides ena_profile (privacy-safe column metadata), ena_inspect (triage), ena_fit, ena_compare_groups (mean-rotation group comparison), ena_plot (rendered network views), and ena_accumulate. Prefer a file path over pasted data so raw rows stay on your machine.",
+  "author": {
+    "name": "Cody L Marquart",
+    "email": "clmarquart@wisc.edu"
+  },
+  "homepage": "https://qe-libs.org/mcp/qe-mcp-server-ena/",
+  "documentation": "https://qe-libs.org/mcp/qe-mcp-server-ena/",
+  "license": "GPL-3.0-only",
+  "keywords": [
+    "ena",
+    "epistemic-network-analysis",
+    "quantitative-ethnography",
+    "discourse-analysis",
+    "learning-analytics",
+    "wasm"
+  ],
+  "server": {
+    "type": "node",
+    "entry_point": "server.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/server.js"
+      ],
+      "env": {}
+    }
+  },
+  "tools": [
+    {
+      "name": "ena_profile",
+      "description": "Privacy-safe column metadata for a local CSV — no raw data transmitted."
+    },
+    {
+      "name": "ena_inspect",
+      "description": "Triage a dataset for ENA suitability; suggests codes, units, and conversations."
+    },
+    {
+      "name": "ena_fit",
+      "description": "Fit a full ENA model; returns a reusable model_id and a network plot."
+    },
+    {
+      "name": "ena_compare_groups",
+      "description": "Mean-rotation comparison of two groups; returns a model_id and plots."
+    },
+    {
+      "name": "ena_plot",
+      "description": "Render a network view (all, group, unit, comparison, subtraction) from a cached model_id."
+    },
+    {
+      "name": "ena_accumulate",
+      "description": "Accumulation step only — raw per-unit co-occurrence networks."
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qe-mcp/server-ena",
-  "version": "0.1.5",
-  "description": "MCP server for Epistemic Network Analysis — WASM backend, zero Python dependency",
+  "version": "0.1.7",
+  "description": "MCP server for Epistemic Network Analysis \u2014 WASM backend, zero Python dependency",
   "type": "module",
   "main": "server.js",
   "bin": {

package/scripts/build-mcpb.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# build-mcpb.sh — Produce a cross-platform .mcpb desktop-extension bundle.
+#
+# Stages only the runtime files plus a pure JS/WASM node_modules (optional deps
+# omitted, so the native @resvg/resvg-js is excluded and the bundle works on any
+# platform). PNG output is disabled in the bundle; SVG + interactive HTML remain.
+#
+# Usage:  bash scripts/build-mcpb.sh
+# Output: dist/server-ena.mcpb
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+STAGE="$(mktemp -d)/server-ena"
+OUT="${ROOT}/dist"
+
+echo "Staging runtime files → ${STAGE}"
+mkdir -p "${STAGE}" "${OUT}"
+
+# Runtime files only (server.js resolves qeviz from node_modules, so the
+# repo-root qeviz-*.js/html dev artifacts and tests are not needed).
+cp "${ROOT}/server.js"     "${STAGE}/"
+cp "${ROOT}/manifest.json" "${STAGE}/"
+cp "${ROOT}/package.json"  "${STAGE}/"
+
+# Keep the bundle's manifest version in lockstep with package.json.
+VERSION="$(node -e "process.stdout.write(require('${ROOT}/package.json').version)")"
+node -e "
+  const fs = require('fs');
+  const p = '${STAGE}/manifest.json';
+  const m = JSON.parse(fs.readFileSync(p, 'utf8'));
+  m.version = '${VERSION}';
+  fs.writeFileSync(p, JSON.stringify(m, null, 2) + '\n');
+"
+echo "Manifest version synced to ${VERSION}"
+cp "${ROOT}/package-lock.json" "${STAGE}/" 2>/dev/null || true
+[ -f "${ROOT}/README.md" ] && cp "${ROOT}/README.md" "${STAGE}/"
+[ -f "${ROOT}/.npmrc" ]    && cp "${ROOT}/.npmrc"    "${STAGE}/"
+
+echo "Installing production deps without optional (pure JS/WASM)…"
+( cd "${STAGE}" && npm install --omit=optional --omit=dev --no-audit --no-fund --silent )
+
+# Drop the .npmrc so the registry token/config isn't shipped in the bundle.
+rm -f "${STAGE}/.npmrc"
+
+# Some npm versions (e.g. 9.x) still materialize root-level optionalDependencies
+# despite --omit=optional. Remove the native rasterizer explicitly so the bundle
+# stays pure JS/WASM and cross-platform. The server degrades gracefully without it.
+rm -rf "${STAGE}"/node_modules/@resvg
+
+# Sanity: the native rasterizer must NOT be present in the bundle.
+if [ -d "${STAGE}/node_modules/@resvg" ]; then
+    echo "ERROR: @resvg present in bundle — not cross-platform. Aborting." >&2
+    exit 1
+fi
+
+echo "Packing bundle…"
+mcpb pack "${STAGE}" "${OUT}/server-ena.mcpb"
+
+echo ""
+echo "Built: ${OUT}/server-ena.mcpb"
+mcpb info "${OUT}/server-ena.mcpb" 2>/dev/null | head -20 || true

package/server.js

@@ -506,10 +506,35 @@ function toolInspect({ data_path, data_csv }) {
         recommended = true;
         confidence  = 'low';
         reason = `Found ${nCodes} binary code columns but no clear unit/conversation columns by name.`;
+    } else if (nCodes === 1) {
+        recommended = false;
+        confidence  = 'low';
+        reason = `Only 1 binary code column was detected. ENA models co-occurrence ` +
+            `*between* codes, so it needs at least 2 (ideally 4+) binary presence/absence columns.`;
     } else {
         recommended = false;
         confidence  = 'low';
-        reason = `Found only ${nCodes} binary column(s). ENA typically requires 4+ binary code columns.`;
+        reason = `No binary (0/1) code columns were detected in this dataset. ENA models the ` +
+            `co-occurrence of *codes* — columns that mark, for each row, whether a concept, ` +
+            `behavior, or feature is present (1) or absent (0). This dataset has none, so ENA ` +
+            `cannot be run on it as-is.`;
+    }
+
+    // Actionable guidance for the not-applicable cases, so Claude can explain
+    // to the user *why* ENA doesn't fit and what would be needed.
+    let guidance = null;
+    if (!recommended) {
+        const needs =
+            'For a dataset to be analyzable with ENA it needs:\n' +
+            '  • 2+ binary (0/1) CODE columns — each marking presence/absence of a concept or behavior per row\n' +
+            '  • a UNIT column identifying who or what each row belongs to\n' +
+            '  • a CONVERSATION column grouping rows into episodes';
+        guidance = nCodes === 0
+            ? `${needs}\n\nThis dataset appears to contain no coded columns. If it is uncoded text or ` +
+              `raw events, each concept of interest must first be turned into a 0/1 column (a ` +
+              `qualitative-coding step) before ENA can be applied. If you expected coded columns, ` +
+              `check that they use 0/1 values rather than text labels.`
+            : `${needs}\n\nAdd more binary code columns, or use a standard statistical analysis instead.`;
     }
 
     let nextStep = {};
@@ -554,6 +579,8 @@ function toolInspect({ data_path, data_csv }) {
             suggestedConvos.slice(0,3).map(c => `${c.column} (n=${c.n_unique}, score=${c.score})`).join(', '));
     for (const [col, vals] of Object.entries(suggestedGroups))
         summaryLines.push(`Likely group column: '${col}' → ${JSON.stringify(vals)}`);
+    if (guidance)
+        summaryLines.push('', guidance);
 
     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.'
@@ -564,6 +591,7 @@ function toolInspect({ data_path, data_csv }) {
         ena_recommended:         recommended,
         confidence,
         reason,
+        guidance,
         n_rows:                  nRows,
         n_cols:                  headers.length,
         suggested_codes:         codeCols,
@@ -1078,6 +1106,9 @@ const TOOLS = [
             'Inspect a dataset and recommend whether ENA is an appropriate analysis. ' +
             'Call this FIRST whenever a user provides tabular data and asks for analysis. ' +
             'Returns ena_recommended, confidence, suggested codes/units/conversations, and a ready-to-use next_step call. ' +
+            'When ena_recommended is false, the result includes a "guidance" field explaining why the data is not ENA-shaped ' +
+            '(e.g. no binary code columns) and what would be needed — relay this to the user rather than silently failing or ' +
+            'claiming the connector is unavailable. ' +
             'PRIVACY: prefer data_path over data_csv so raw data stays local. ' +
             'If the user has not yet indicated whether their data is sensitive, ask before using data_csv. ' +
             'If they indicate sensitivity, use ena_profile instead (no raw data transmitted).',