Skip to content

Commit 6cd46b5

Browse files
dgageotdgageot
committed
Add mcp/node-code-sandbox
Signed-off-by: David Gageot <david.gageot@docker.com>
1 parent 76905b9 commit 6cd46b5

File tree

3 files changed

+150
-0
lines changed

3 files changed

+150
-0
lines changed

‎prompts/catalog.yaml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2866,3 +2866,19 @@ registry:
28662866
- name: search_wikipedia
28672867
prompts: 0
28682868
resources: {}
2869+
node-code-sandbox:
2870+
description: A Node.js–based Model Context Protocol server that spins up disposable Docker containers to execute arbitrary JavaScript.
2871+
title: Node.js Sandbox
2872+
ref: github:docker/labs-ai-tools-for-devs?ref=main&path=prompts/mcp/node-code-sandbox.md
2873+
readme: https://github.com/docker/labs-ai-tools-for-devs/blob/main/prompts/mcp/readmes/node-code-sandbox.md
2874+
source: https://github.com/alfonsograziano/node-code-sandbox-mcp/tree/master
2875+
icon: https://cdn.jsdelivr.net/npm/simple-icons@v7/icons/nodedotjs.svg
2876+
tools:
2877+
- name: get_dependency_types
2878+
- name: run_js
2879+
- name: run_js_ephemeral
2880+
- name: sandbox_exec
2881+
- name: sandbox_initialize
2882+
- name: sandbox_stop
2883+
prompts: 0
2884+
resources: {}

‎prompts/mcp/node-code-sandbox.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
mcp:
3+
- container:
4+
image: mcp/node-code-sandbox:latest
5+
workdir: /app
6+
source:
7+
url: https://github.com/alfonsograziano/node-code-sandbox-mcp/tree/master
8+
---

‎prompts/mcp/readmes/node-code-sandbox.md

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Node-code-sandbox MCP Server
2+
3+
A Node.js–based Model Context Protocol server that spins up disposable Docker containers to execute arbitrary JavaScript.
4+
5+
[What is an MCP Server?](https://www.anthropic.com/news/model-context-protocol)
6+
7+
## Characteristics
8+
Attribute|Details|
9+
|-|-|
10+
**Image Source**|Official Image
11+
**Docker Image**|[mcp/node-code-sandbox](https://hub.docker.com/repository/docker/mcp/node-code-sandbox)
12+
**Author**|[alfonsograziano](https://github.com/alfonsograziano)
13+
**Repository**|https://github.com/alfonsograziano/node-code-sandbox-mcp
14+
**Dockerfile**|https://github.com/alfonsograziano/node-code-sandbox-mcp/blob/master/Dockerfile
15+
**Docker Image built by**|Docker Inc.
16+
**Docker Scout Health Score**| ![Docker Scout Health Score](https://api.scout.docker.com/v1/policy/insights/org-image-score/badge/mcp/node-code-sandbox)
17+
**Verify Signature**|`COSIGN_REPOSITORY=mcp/signatures cosign verify mcp/node-code-sandbox --key https://raw.githubusercontent.com/docker/keyring/refs/heads/main/public/mcp/latest.pub`
18+
**Licence**|
19+
20+
## Available Tools
21+
Tools provided by this Server|Short Description
22+
-|-
23+
`get_dependency_types`|Given an array of npm package names (and optional versions),
24+
fetch whether each package ships its own TypeScript definitions
25+
or has a corresponding @types/… package, and return the raw .d.ts text.|
26+
`run_js`|Install npm dependencies and run JavaScript code inside a running sandbox container.|
27+
`run_js_ephemeral`|Run a JavaScript snippet in a temporary disposable container with optional npm dependencies, then automatically clean up.|
28+
`sandbox_exec`|Execute one or more shell commands inside a running sandbox container.|
29+
`sandbox_initialize`|Start a new isolated Docker container running Node.js.|
30+
`sandbox_stop`|Terminate and remove a running sandbox container.|
31+
32+
---
33+
## Tools Details
34+
35+
#### Tool: **`get_dependency_types`**
36+
Given an array of npm package names (and optional versions),
37+
fetch whether each package ships its own TypeScript definitions
38+
or has a corresponding @types/… package, and return the raw .d.ts text.
39+
40+
Useful whenwhen you're about to run a Node.js script against an unfamiliar dependency
41+
and want to inspect what APIs and types it exposes.
42+
Parameters|Type|Description
43+
-|-|-
44+
`dependencies`|`array`|
45+
46+
---
47+
#### Tool: **`run_js`**
48+
Install npm dependencies and run JavaScript code inside a running sandbox container.
49+
After running, you must manually stop the sandbox to free resources.
50+
The code must be valid ESModules (import/export syntax). Best for complex workflows where you want to reuse the environment across multiple executions.
51+
When reading and writing from the Node.js processes, you always need to read from and write to the "./files" directory to ensure persistence on the mounted volume.
52+
Parameters|Type|Description
53+
-|-|-
54+
`code`|`string`|JavaScript code to run inside the container.
55+
`container_id`|`string`|Docker container identifier
56+
`dependencies`|`array` *optional*|A list of npm dependencies to install before running the code. Each item must have a `name` (package) and `version` (range). If none, returns an empty array.
57+
`listenOnPort`|`number` *optional*|If set, leaves the process running and exposes this port to the host.
58+
59+
---
60+
#### Tool: **`run_js_ephemeral`**
61+
Run a JavaScript snippet in a temporary disposable container with optional npm dependencies, then automatically clean up.
62+
The code must be valid ESModules (import/export syntax). Ideal for simple one-shot executions without maintaining a sandbox or managing cleanup manually.
63+
When reading and writing from the Node.js processes, you always need to read from and write to the "./files" directory to ensure persistence on the mounted volume.
64+
This includes images (e.g., PNG, JPEG) and other files (e.g., text, JSON, binaries).
65+
66+
Example:
67+
```js
68+
import fs from "fs/promises";
69+
await fs.writeFile("./files/hello.txt", "Hello world!");
70+
console.log("Saved ./files/hello.txt");
71+
```
72+
Parameters|Type|Description
73+
-|-|-
74+
`code`|`string`|JavaScript code to run inside the ephemeral container.
75+
`dependencies`|`array` *optional*|A list of npm dependencies to install before running the code. Each item must have a `name` (package) and `version` (range). If none, returns an empty array.
76+
`image`|`string` *optional*|Docker image to use for ephemeral execution. e.g. - **node:lts-slim**: Node.js LTS version, slim variant. (Lightweight and fast for JavaScript execution tasks.)
77+
- **mcr.microsoft.com/playwright:v1.52.0-noble**: Playwright image for browser automation. (Preconfigured for running Playwright scripts.)
78+
- **alfonsograziano/node-chartjs-canvas:latest**: Chart.js image for chart generation and mermaid charts generation. ('Preconfigured for generating charts with chartjs-node-canvas and Mermaid. Minimal Mermaid example:
79+
import fs from "fs";
80+
import { run } from "@mermaid-js/mermaid-cli";
81+
fs.writeFileSync("./files/diagram.mmd", "graph LR; A-->B;", "utf8");
82+
await run("./files/diagram.mmd", "./files/diagram.svg");)
83+
84+
---
85+
#### Tool: **`sandbox_exec`**
86+
Execute one or more shell commands inside a running sandbox container. Requires a sandbox initialized beforehand.
87+
Parameters|Type|Description
88+
-|-|-
89+
`commands`|`array`|
90+
`container_id`|`string`|
91+
92+
---
93+
#### Tool: **`sandbox_initialize`**
94+
Start a new isolated Docker container running Node.js. Used to set up a sandbox session for multiple commands and scripts.
95+
Parameters|Type|Description
96+
-|-|-
97+
`image`|`string` *optional*|
98+
`port`|`number` *optional*|If set, maps this container port to the host
99+
100+
---
101+
#### Tool: **`sandbox_stop`**
102+
Terminate and remove a running sandbox container. Should be called after finishing work in a sandbox initialized with sandbox_initialize.
103+
Parameters|Type|Description
104+
-|-|-
105+
`container_id`|`string`|
106+
107+
---
108+
## Use this MCP Server
109+
110+
```json
111+
{
112+
"mcpServers": {
113+
"node-code-sandbox": {
114+
"command": "docker",
115+
"args": [
116+
"run",
117+
"-i",
118+
"--rm",
119+
"mcp/node-code-sandbox"
120+
]
121+
}
122+
}
123+
}
124+
```
125+
126+
[Why is it safer to run MCP Servers with Docker?](https://www.docker.com/blog/the-model-context-protocol-simplifying-building-ai-apps-with-anthropic-claude-desktop-and-docker/)

0 commit comments

Comments
 (0)