ena-mcp

An MCP server that lets an AI assistant drive Epistemic Network Analysis models hosted on the webENA cloud service (app.epistemicnetwork.org).

Models are computed by webENA's own R / OpenCPU + rENA backend, so the numbers are canonical rENA output — this is not a reimplementation or an approximation. The server handles transport, decoding, and presentation.

繁體中文說明：README.zh-TW.md

---

What it does

Once connected, an assistant can list your ENA projects, inspect a set's column roles and algorithm parameters, run the model, and get back per-unit ENA scores, edge weights, node positions, variance explained, eigenvalues, the rotation matrix, and goodness-of-fit correlations — then plot networks, sweep the stanza window, run group statistics, and pull the raw discourse behind any connection.

Protocol details are documented in docs/PROTOCOL.md, derived from observed traffic against a live account.

Unofficial. This project is not affiliated with, endorsed by, or supported by the Epistemic Analytics Lab or UW–Madison. It talks to a private API that carries no compatibility guarantee. See Limitations.

---

Install

git clone https://github.com/Ian3738/ena-mcp.git
cd ena-mcp
npm install && npm run build

Requires Node.js 20 or newer.

Authentication

webENA authenticates with an HttpOnly session cookie. There is no API token, and the login endpoint is not part of the app bundle, so the cookie has to be copied manually once. Accounts registered through Google SSO cannot use programmatic username/password login at all.

1. Sign in at https://app.epistemicnetwork.org
2. Open DevTools → Application → Cookies → app.epistemicnetwork.org
3. Copy the session cookie as name=value (e.g. connect.sid=s%3A…)
4. Store it:

mkdir -p ~/.ena-mcp && chmod 700 ~/.ena-mcp
printf '%s' 'connect.sid=PASTE_HERE' > ~/.ena-mcp/cookie
chmod 600 ~/.ena-mcp/cookie

Alternatives: set ENA_SESSION_COOKIE directly, or point ENA_SESSION_COOKIE_FILE at another path.

The cookie expires. When it does, every tool returns the same actionable error — fetch a fresh one. The cookie value is redacted from all tool output before it leaves the process.

Verify

npm run smoke

Checks the cookie, lists projects, and opens the socket.io connection. To run a model end to end:

npm run smoke -- --set "<setID>" --project "<projectName>"

Connect an MCP client

Add to claude_desktop_config.json (or any MCP client's server config):

{
  "mcpServers": {
    "ena": {
      "command": "node",
      "args": ["/absolute/path/to/ena-mcp/dist/src/index.js"],
      "env": { "ENA_SESSION_COOKIE_FILE": "/Users/you/.ena-mcp/cookie" }
    }
  }
}

Configuration

Variable	Default	Purpose
ENA_SESSION_COOKIE	—	Session cookie value
ENA_SESSION_COOKIE_FILE	~/.ena-mcp/cookie	File containing it
ENA_ORIGIN	https://app.epistemicnetwork.org	Server origin
ENA_TIMEOUT_MS	360000	Request timeout (matches the server's own 6-minute watchdog)

---

Tools

Session and browsing

Tool	Purpose
ena_check_session	Validate the cookie and list projects. Run this first
ena_get_project	Folders, uploaded data files, and sets inside a project
ena_get_set	Column roles and algorithm parameters, without computing

Modelling

Tool	Purpose
ena_run_model	Core. Returns per-unit ENA scores, edge weights, node positions, variance explained, eigenvalues, rotation matrix, goodness of fit. Algorithm parameters can be overridden per run
ena_sweep_window	Run across several moving-window sizes and compare variance explained and GOF — for justifying a window choice
ena_optimal_window	The server's recommended window size
ena_get_correlations	Co-registration correlations (reviewers expect these reported)
ena_get_methods	webENA's auto-generated Methods paragraph for the current model

Data and qualitative evidence

Tool	Purpose
ena_get_data	The raw CSV behind a set — for reading utterances, checking coding, pulling quotes
ena_get_conversation	The discourse rows behind a selected connection

Statistics and visualization

Tool	Purpose
ena_compare_groups	Between-group test (Mann-Whitney U / t-test)
ena_plot_network	ENA network as SVG
ena_plot_subtraction	Between-group subtraction network as SVG

A typical flow:

ena_check_session → ena_get_project → ena_get_set
  → ena_run_model → ena_plot_network / ena_compare_groups
  → ena_get_data (quotes) → ena_get_methods (write-up)

Model results are cached per set for the session, so plotting and comparison do not re-run the model.

---

Limitations

1. Parameters yes, selections no. /set/generate strips selections (ENA.getSaveableSet = set => _.omit(set, "selections", "set")) and the server resolves them from the persisted selectionsRef. Therefore:

• ✅ Algorithm parameters (stanzaSize, stanza, sphereNorm, centerZero, ordered) take effect directly
• ❌ Which individual units / conversations / codes are selected requires /set/save-model plus a rebuilt selection tree — effectively reproducing two browser web workers. Change selections in the web UI, then run the model here.

2. This is a private API. webENA publishes no API contract. A release can break this server without warning. docs/PROTOCOL.md records what was observed so the differences can be re-derived.

3. Data leaves the machine. Every model run computes discourse on UW–Madison's servers. The data already lives there, but for human-subjects work under an ethics protocol this belongs in the risk assessment.

4. Cookies expire and must be refreshed by hand.

---

Alternative

rENA's CRAN maintainer publishes @qe-mcp/server-ena, which runs ENA locally via WASM and installs as a one-click .mcpb.

The two do not overlap:

	ena-mcp	@qe-mcp/server-ena
Existing sets in a webENA account	✅ read and model	❌ not visible
Offline / data stays local	❌	✅
Change individual unit/code selections	❌	✅
API stability	reverse-engineered	package-versioned

Installing both is reasonable: this one to work with existing cloud projects, the official one for local exploration and CSV experiments.

---

Development

npm run build     # compile
npm test          # decoder tests (13)
npm run dev       # watch mode

License

MIT — see LICENSE.