# @qe-mcp/server-ena

MCP server for [Epistemic Network Analysis (ENA)](https://www.epistemicnetwork.org/), powered by a WebAssembly backend. Zero Python dependency — runs entirely in Node.js.

Designed for use with [Claude Desktop](https://claude.ai/download) and [Claude Code](https://claude.ai/code).

---

## What it does

Gives Claude a set of ENA tools that run **locally on your machine**. The WASM model computation never leaves your computer. Only results (node positions, plots, summary statistics) are returned to Claude.

| Tool | Description |
|---|---|
| `ena_profile` | Privacy-safe column metadata — no raw data transmitted |
| `ena_inspect` | Triage a dataset: is ENA appropriate? Returns suggested parameters |
| `ena_fit` | Full ENA pipeline → model + inline PNG plot |
| `ena_compare_groups` | Mean-rotation group comparison → model + inline PNG plot |
| `ena_plot` | Any view from a cached model (all / group / unit / comparison / subtraction) |
| `ena_accumulate` | Accumulation step only, no rotation or projection |

---

## Prerequisites

- **Node.js** 18 or later
- **Claude Desktop** or **Claude Code**

---

## Installation

### 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)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac):

```json
{
  "mcpServers": {
    "ena": {
      "command": "npx",
      "args": ["--yes", "@qe-mcp/server-ena"]
    }
  }
}
```

Restart Claude Desktop.

### Option B — global install

```bash
npm install -g @qe-mcp/server-ena
```

Then in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ena": {
      "command": "server-ena"
    }
  }
}
```

### Option C — local clone (development)

```bash
git clone <repo-url> server-ena
cd server-ena
npm install
```

```json
{
  "mcpServers": {
    "ena": {
      "command": "node",
      "args": ["/absolute/path/to/server-ena/server.js"]
    }
  }
}
```

### Dev builds

Pre-release builds are published only to the QE GitLab registry with a `dev` tag.
To use one, add the scope mapping once and pin `@dev`:

```bash
echo "@qe-mcp:registry=https://gitlab.com/api/v4/projects/22522458/packages/npm/" >> ~/.npmrc
echo "@qe-libs:registry=https://gitlab.com/api/v4/projects/22522458/packages/npm/" >> ~/.npmrc
npx --yes @qe-mcp/server-ena@dev
```

### Verify

In Claude Desktop, open a new conversation and ask:

> "What ENA tools do you have available?"

Claude should list `ena_profile`, `ena_inspect`, `ena_fit`, `ena_compare_groups`, `ena_plot`, and `ena_accumulate`.

---

## Skill (claude.ai / Claude Desktop / Claude Science)

The [`skill/ena-analysis/`](skill/ena-analysis/) folder contains a companion skill that teaches
Claude the full ENA workflow — privacy gate, triage, fitting, and plot
exploration — so it drives the connector correctly without per-conversation
prompting.

To install:

```bash
cd skill && zip -r ena-analysis.zip ena-analysis
```

Then upload `ena-analysis.zip` under **Settings → Customize → Skills**
(claude.ai / Claude Desktop) or **Customize → Skills** (Claude Science).

---

## Privacy model

**The WASM computation always runs locally.** What reaches Claude depends on how you provide data:

| Method | What Claude sees |
|---|---|
| `data_path` (file path) | Nothing from the file — only model results (node positions, unit labels, plots) |
| `data_csv` (inline CSV) | The full raw CSV, as a tool call argument |

For research data, always use `data_path`. Use `data_csv` only for small toy or demo datasets.

Unit labels (the values in your unit column, e.g. participant IDs) are included in model results regardless of input method. If those are sensitive, be aware they will appear in the conversation.

### Privacy gate hook

To technically enforce the `data_path` preference and block large inline CSVs, install the privacy gate hook. This intercepts tool calls before they execute and rejects any `data_csv` payload with more than 50 rows.

**Step 1 — Copy the hook script:**

```bash
mkdir -p ~/.claude/hooks
cp hooks/ena-privacy-gate.mjs ~/.claude/hooks/
```

**Step 2 — Add to `~/.claude/settings.json`:**

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__(ena-wasm|ena|enajs)__(ena_inspect|ena_fit|ena_accumulate|ena_compare_groups)",
        "hooks": [
          {
            "type": "command",
            "command": "node /Users/YOUR_USERNAME/.claude/hooks/ena-privacy-gate.mjs"
          }
        ]
      }
    ]
  }
}
```

Replace `YOUR_USERNAME` with your macOS username. If you already have a `hooks` block in `settings.json`, add the new entry to the existing `PreToolUse` array.

The hook takes effect immediately — no restart needed.

**Threshold:** ≤ 50 rows of `data_csv` are allowed (toy/demo use). Larger payloads are blocked with a message instructing Claude to ask for a file path instead.

---

## Usage

### Basic analysis

```
"Analyze /path/to/data.csv"
```

Claude will call `ena_inspect` first, confirm ENA is appropriate, then call `ena_fit` and return a network plot.

### Sensitive data

```
"I have sensitive data at /path/to/data.csv — what can you tell me about its structure?"
```

Claude will call `ena_profile` (column metadata only, no raw data transmitted), identify appropriate parameters, then run the model with `data_path`.

### Group comparison

```
"Compare First vs Second half using data at /path/to/data.csv, unit column UserName, conversation column GameHalf"
```

Claude will call `ena_compare_groups` and return a comparison plot. Follow up with:

```
"Show me the subtraction network"
"Show me the First half mean network"
"Show me unit steven_z"
```

These use `ena_plot` with the cached `model_id` — no refitting.

---

## Output

Each fitting or plotting call returns:

- **`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.

---

## Testing

```bash
node test-mcp.mjs \
  /path/to/data.csv \
  UnitColumn ConversationColumn \
  Code1 Code2 Code3 Code4
```

This drives the server over stdin/stdout (same transport Claude uses) and saves all PNG outputs to `/tmp/ena-test-N.png`.

To test group comparison, edit `test-mcp.mjs` and set `GROUP_COL`, `GROUP1`, `GROUP2` at the top of the file.