Runs persistent Node.js REPL sessions via node-repl-cli (MCP tools or stateless CLI): create named sessions, exec JavaScript with REPL semantics, read history, remove sessions. Use when the user needs isolated Node REPL contexts, agent-safe code execution without an interactive shell, or when they mention node-repl-cli, REPL sessions, or this package’s MCP server.
Use node-repl-cli so the agent never drives an interactive REPL (stdin / readline). Prefer MCP when the host exposes MCP tools; otherwise use CLI subprocesses.
| Situation | Use |
|---|---|
| MCP host with this package as stdio server | Tools: repl_cli_session_*, repl_cli_pkg_*, repl_cli_ping |
| Shell / subprocess only (no MCP) | node-repl-cli create, exec, history, list, remove, `pkg <name> install |
MCP sessions live only in the MCP process. Standalone CLI sessions use a coordinator (serve) + lock file; they are not the same registry unless you orchestrate that yourself.
repl_cli_pkg_install — { "name": "<session>", "packages": ["<spec>", ...], "saveDev"?: false } so that session has its own node_modules under a user-local directory (same path the daemon uses after create).repl_cli_session_create — { "name": "<session>" } once per logical workspace or task. Session names: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$.repl_cli_session_exec — { "name": "<session>", "code": "<js>" } for each snippet. Context persists in that session (like node REPL).repl_cli_session_history — { "name": "<session>" } when transcripts or prior I/O matter.repl_cli_pkg_list — { "name": "<session>" } to read declared dependencies / devDependencies from that workspace package.json.repl_cli_pkg_remove — uninstall packages when no longer needed.repl_cli_session_remove — { "name": "<session>" } when finished to free the daemon (workspace folder may remain on disk).Responses are text content whose body is JSON (ok, result / entries, or errors).
Assume node-repl-cli is on PATH (or use npx node-repl-cli / node /path/to/dist/cli.js).
node-repl-cli pkg <name> install <npm-spec> [<npm-spec> ...]
node-repl-cli pkg <name> list
node-repl-cli create <name>
node-repl-cli exec <name> -c "<javascript>"
node-repl-cli history <name>
node-repl-cli list
node-repl-cli pkg <name> remove <package> [<package> ...]
node-repl-cli remove <name>
--addr by default: lock file + autostart of serve. Override with REPL_CLI_ADDR if needed.REPL_CLI_STATE_DIR (directory containing coordinator.json and sessions/). Optional REPL_CLI_NPM_CACHE for npm’s cache when running pkg … install / remove.REPL_CLI_AUTOSTART=0 and run node-repl-cli serve in a long-lived process first.Use these patterns when the host only has a shell tool. Replace demo with a valid session name (^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$). Paths/ports are illustrative.
| Command | Typical stdout (last line or whole body) | Exit code |
|---|---|---|
node-repl-cli create demo | {"name":"demo","status":"ready","port":58432,"pid":12345,"createdAt":"…","workspace":"…/sessions/demo"} | 0 |
node-repl-cli exec demo -c "1+1" | {"input":"…","output":"2","error":null,"streams":{…}} | 0 if error is null, else 1 |
node-repl-cli history demo | JSON array of { input, output, error, streams } | 0 |
node-repl-cli list | [{"name":"demo","status":"ready",…,"workspace":"…"}] (JSON array) | 0 |
node-repl-cli pkg demo list | {"workspace":"…","dependencies":{…},"devDependencies":{…}} | 0 |
node-repl-cli pkg demo install lodash | npm log lines, then {"ok":true,"code":0} | 0 on success |
node-repl-cli pkg demo remove lodash | npm log lines, then {"ok":true,"code":0} | 0 on success |
node-repl-cli remove demo | {"ok":true} | 0 |
Parsing tips: (1) For exec, treat non‑null error as failure even if the process printed other text. (2) For pkg install / pkg remove, scan for the last JSON object or rely on exit code; npm may write many lines before the final { "ok": true, "code": 0 }. (3) create fails with a message on stderr if the name already exists. (4) list stdout is a top-level JSON array (not wrapped in an object).
POST /mcp/tools/…; real transport is stdio MCP)