skills / nodejs-mcp.md
skills / nodejs-mcp.md
The nodejs-mcp plugin gives the AI tools to run JavaScript (ESM, import/export) inside sandboxes. Each sandbox is a local folder. There is no Docker. Write files to the Output Folder (default name files) to keep them and get them back later.
Error:, read why and retry.container_id from sandbox_initialize in every other tool. Copy it each time../files/... (the Output Folder; default name files). Files there are returned with results and can be read/listed later. Files written elsewhere are lost.import/export and Node built-ins (node:fs, node:path, …). Use the global fetch for network, not node-fetch.image/port are ignored (no Docker). Do not set them.read_text_file reads text only. Binary files are refused; long files are cut off.list_directory, read_text_file, write_text_file are **relative to the Output Folder (e.g. notes/hello.txt). ../ is blocked.sandbox_exec cannot use backticks ` or $().search_npm_packages and get_dependency_types need internet.sandbox_initializeCreate a sandbox. Returns an id like ws-1a2b3c….
Args: none needed (image/port are ignored).
Result: the id string — use it in every later tool.
run_js_ephemeralRun one script, then clean up automatically. Use for a single one-shot run.
Args: code (string, required); dependencies? (list of {name, version?}); image? (ignored).
run_jsRun a script in a kept sandbox. Use when you need several runs in the same place. Call sandbox_stop when done.
Args: container_id (string); code (string); dependencies? ({name,version?}); listenOnPort`? (number).
sandbox_execRun shell commands in a running sandbox. Each command runs in the sandbox's working folder. Returns stdout/stderr. No backticks or $().
Args: container_id (string); commands (string list, in order).
sandbox_stopDelete a sandbox. Call it when you are done. Args: `container_id (string).
container_idThese work in the Output Folder (default files). Paths are relative to it.
list_directoryList files and subfolders. A folder name ends with /.
Args: container_id (string); path`? (string, a subfolder).
read_text_fileRead a text file. Binary files are refused; long files are cut off.
Args: container_id (string); path (string), e.g. notes/hello.txt.
write_text_fileWrite a text file. Makes folders as needed.
Args: container_id (string); path(string);content (string).
search_npm_packagesSearch npm. Use + to join words, e.g. react+components.
Args: searchTerm (string); qualifiers (optional: author/maintainer/scope/keywords/not/is/bestExact).
get_dependency_typesCheck if a package ships types (.d.ts or @types).
Args: dependencies (list of {name, version?}`.
Error:, the step failed — fix and retry.run_js/run_js_ephemeral add a Telemetry: block at the end (timing info). You can ignore it.Goal: run a script that writes a file and prints a number.
run_js_ephemeral with this code:
hello.txt, and a Telemetry block.Goal: run several times and manage files.
sandbox_initialize → copy the container_id.run_js (with that container_id`) — it runs in the same place each time.Goal: pick a package, then run code that uses it.
search_npm_packages with searchTerm(e.g.qr`).run_js_ephemeral (or run_js) with dependencies: [{ "name": "qr", "version": "^1.0.0" }]`.Script Timeout — max seconds per run (1–3600, default 30).Workspace Lifetime — seconds before an idle sandbox is removed (60–86400, default 3600).Output Folder — folder name for kept files (default files).The nodejs-mcp plugin gives the AI tools to run JavaScript (ESM, import/export) inside sandboxes. Each sandbox is a local folder. There is no Docker. Write files to the Output Folder (default name files) to keep them and get them back later.
Error:, read why and retry.container_id from sandbox_initialize in every other tool. Copy it each time../files/... (the Output Folder; default name files). Files there are returned with results and can be read/listed later. Files written elsewhere are lost.import/export and Node built-ins (node:fs, node:path, …). Use the global fetch for network, not node-fetch.image/port are ignored (no Docker). Do not set them.read_text_file reads text only. Binary files are refused; long files are cut off.list_directory, read_text_file, write_text_file are **relative to the Output Folder (e.g. notes/hello.txt). ../ is blocked.sandbox_exec cannot use backticks ` or $().search_npm_packages and get_dependency_types need internet.sandbox_initializeCreate a sandbox. Returns an id like ws-1a2b3c….
Args: none needed (image/port are ignored).
Result: the id string — use it in every later tool.
run_js_ephemeralRun one script, then clean up automatically. Use for a single one-shot run.
Args: code (string, required); dependencies? (list of {name, version?}); image? (ignored).
run_jsRun a script in a kept sandbox. Use when you need several runs in the same place. Call sandbox_stop when done.
Args: container_id (string); code (string); dependencies? ({name,version?}); listenOnPort`? (number).
sandbox_execRun shell commands in a running sandbox. Each command runs in the sandbox's working folder. Returns stdout/stderr. No backticks or $().
Args: container_id (string); commands (string list, in order).
sandbox_stopDelete a sandbox. Call it when you are done. Args: `container_id (string).
container_idThese work in the Output Folder (default files). Paths are relative to it.
list_directoryList files and subfolders. A folder name ends with /.
Args: container_id (string); path`? (string, a subfolder).
read_text_fileRead a text file. Binary files are refused; long files are cut off.
Args: container_id (string); path (string), e.g. notes/hello.txt.
write_text_fileWrite a text file. Makes folders as needed.
Args: container_id (string); path(string);content (string).
search_npm_packagesSearch npm. Use + to join words, e.g. react+components.
Args: searchTerm (string); qualifiers (optional: author/maintainer/scope/keywords/not/is/bestExact).
get_dependency_typesCheck if a package ships types (.d.ts or @types).
Args: dependencies (list of {name, version?}`.
Error:, the step failed — fix and retry.run_js/run_js_ephemeral add a Telemetry: block at the end (timing info). You can ignore it.Goal: run a script that writes a file and prints a number.
run_js_ephemeral with this code:
hello.txt, and a Telemetry block.Goal: run several times and manage files.
sandbox_initialize → copy the container_id.run_js (with that container_id`) — it runs in the same place each time.Goal: pick a package, then run code that uses it.
search_npm_packages with searchTerm(e.g.qr`).run_js_ephemeral (or run_js) with dependencies: [{ "name": "qr", "version": "^1.0.0" }]`.Script Timeout — max seconds per run (1–3600, default 30).Workspace Lifetime — seconds before an idle sandbox is removed (60–86400, default 3600).Output Folder — folder name for kept files (default files)../files/.... Then it appears in list_directory and can be read by read_text_file.list_directory (with that container_id) — see what exists. Folders end with /`.read_text_file (with a path like notes/plan.txt`) — read it.write_text_file (with a path and content`) — create or edit a file.sandbox_stop (with that container_id`) when done.{ "name": "sandbox_initialize", "arguments": {} }
{ "name": "run_js_ephemeral", "arguments": { "code": "console.log('hi');" } }
{ "name": "run_js", "arguments": { "container_id": "ws-1a2b3c", "code": "console.log(2+2)", "dependencies": [ { "name": "lodash", "version": "^4.17.21" } ] } }
{ "name": "sandbox_exec", "arguments": { "container_id": "ws-1a2b3c", "commands": ["node --version"] } }
{ "name": "list_directory", "arguments": { "container_id": "ws-1a2b3c" } }
{ "name": "read_text_file", "arguments": { "container_id": "ws-1a2b3c", "path": "notes/hello.txt" } }
{ "name": "write_text_file", "arguments": { "container_id": "ws-1a2b3c", "path": "notes/todo.txt", "content": "buy milk" } }
import fs from "node:fs/promises";
await fs.writeFile("./files/hello.txt", "hello world");
console.log("result:", 6 * 7);
./files/.... Then it appears in list_directory and can be read by read_text_file.list_directory (with that container_id) — see what exists. Folders end with /`.read_text_file (with a path like notes/plan.txt`) — read it.write_text_file (with a path and content`) — create or edit a file.sandbox_stop (with that container_id`) when done.{ "name": "sandbox_initialize", "arguments": {} }
{ "name": "run_js_ephemeral", "arguments": { "code": "console.log('hi');" } }
{ "name": "run_js", "arguments": { "container_id": "ws-1a2b3c", "code": "console.log(2+2)", "dependencies": [ { "name": "lodash", "version": "^4.17.21" } ] } }
{ "name": "sandbox_exec", "arguments": { "container_id": "ws-1a2b3c", "commands": ["node --version"] } }
{ "name": "list_directory", "arguments": { "container_id": "ws-1a2b3c" } }
{ "name": "read_text_file", "arguments": { "container_id": "ws-1a2b3c", "path": "notes/hello.txt" } }
{ "name": "write_text_file", "arguments": { "container_id": "ws-1a2b3c", "path": "notes/todo.txt", "content": "buy milk" } }
import fs from "node:fs/promises";
await fs.writeFile("./files/hello.txt", "hello world");
console.log("result:", 6 * 7);