Servidor MCP Sandbox de Node.js

Servidor Node.js que implementa el Protocolo de contexto de modelo (MCP) para ejecutar JavaScript arbitrario en contenedores Docker efímeros con instalación de dependencias npm sobre la marcha.

Características

Iniciar y administrar contenedores sandbox aislados de Node.js
Ejecutar comandos de shell arbitrarios dentro de contenedores
Instalar dependencias npm especificadas por trabajo
Ejecute fragmentos de JavaScript del módulo ES y capture la salida estándar
Desmontar los contenedores de forma limpia

Nota: Los contenedores se ejecutan con límites de CPU/memoria controlados.

API

Herramientas

run_js_efímero

Ejecute un script JS único en un contenedor desechable nuevo.

Entradas:

image (cadena, opcional): imagen de Docker a utilizar (predeterminada: node:20-slim ).
code (cadena, obligatorio): código fuente JavaScript a ejecutar.
dependencies (matriz de { name, version } , opcional): paquetes y versiones NPM para instalar (predeterminado: [] ).

Comportamiento:

Crea un contenedor nuevo.
Escribe tu index.js y un package.json mínimo.
Instala las dependencias especificadas.
Ejecuta el script.
Desmonta (quita) el contenedor.
Devuelve la salida estándar capturada.
Si su código guarda algún archivo en el directorio actual, estos archivos se devolverán automáticamente.
- Las imágenes (por ejemplo, PNG, JPEG) se devuelven como contenido image .
- Otros archivos (por ejemplo, .txt , .json ) se devuelven como contenido resource .

Consejo: para recuperar los archivos, simplemente guárdelos durante la ejecución del script.

Ejemplo de llamada:

{
  "name": "run_js_ephemeral",
  "arguments": {
    "image": "node:20-slim",
    "code": "console.log('One-shot run!');",
    "dependencies": [{ "name": "lodash", "version": "^4.17.21" }]
  }
}

Ejemplo para guardar un archivo:

import fs from "fs/promises";

await fs.writeFile("hello.txt", "Hello world!");
console.log("Saved hello.txt");

Esto devolverá la salida de la consola y el archivo hello.txt .

inicialización de sandbox

Inicie un nuevo contenedor de sandbox.

Aporte :
- image ( cadena , opcional, valor predeterminado: node:20-slim ): imagen de Docker para el entorno sandbox
Salida : cadena de identificación del contenedor

sandbox_exec

Ejecute comandos de shell dentro del entorno sandbox en ejecución.

Aporte :
- container_id ( cadena ): ID de sandbox_initialize
- commands ( string[] ): Matriz de comandos de shell para ejecutar
Salida : Salida estándar combinada de cada comando

ejecutar_js

Instalar las dependencias npm y ejecutar el código JavaScript.

Aporte :
- container_id ( cadena ): ID de sandbox_initialize
- code ( cadena ): código fuente JS para ejecutar (módulos ES compatibles)
- dependencies ( matriz de { name, version } , opcional, predeterminado: [] ): nombres de paquetes npm → versiones semver
Comportamiento :
1. Crea un espacio de trabajo temporal dentro del contenedor
2. Escribe index.js y un paquete mínimo package.json
3. Ejecuta npm install --omit=dev --ignore-scripts --no-audit --loglevel=error
4. Ejecuta node index.js y captura la salida estándar
5. Limpia el espacio de trabajo
Salida : Salida estándar del script

parada de la zona de pruebas

Terminar y eliminar el contenedor sandbox.

Aporte :
- container_id ( cadena ): ID de sandbox_initialize
Salida : Mensaje de confirmación

Uso con Claude Desktop

Agregue esto a su claude_desktop_config.json :

{
  "mcpServers": {
    "js-sandbox": {
      "command": "node",
      "args": ["dist/server.js", "stdio"],
      "cwd": "/path/to/js-sandbox-mcp"
    }
  }
}

Nota: asegúrese de que su directorio de trabajo apunte al servidor creado y que Docker esté instalado/en ejecución.

Consejos de uso

Las herramientas basadas en sesiones ( sandbox_initialize ➔ run_js ➔ sandbox_stop ) son ideales cuando desea:
- Mantenga abierto el contenedor de arena de larga duración.
- Ejecute múltiples comandos o scripts en el mismo entorno.
- Instalar y reutilizar dependencias de forma incremental.
La ejecución única con run_js_ephemeral es perfecta para:
- Experimentos rápidos o scripts simples.
- Casos en los que no es necesario mantener dependencias de estado o caché.
- Funcionamiento limpio y atómico sin preocuparse por el desmontaje manual.

¡Elija el flujo de trabajo que mejor se adapte a su caso de uso!

Estibador

Ejecute el servidor en un contenedor (monte el socket Docker si es necesario):

# Build and publish your image locally if needed
# docker build -t alfonsograziano/node-code-sandbox-mcp .

# Run with stdio transport
docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  alfonsograziano/node-code-sandbox-mcp stdio

Uso con VS Code

Botones de instalación rápida (VS Code e Insiders):

Instalar js-sandbox-mcp (NPX) Instalar js-sandbox-mcp (Docker)

Configuración manual : agregue a su archivo VS Code settings.json o .vscode/mcp.json :

"mcp": {
    "servers": {
        "js-sandbox": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-v", "/var/run/docker.sock:/var/run/docker.sock",
                "alfonsograziano/node-code-sandbox-mcp"
              ],
        }
    }
}

Uso con Claude Desktop

Puedes seguir la Guía Oficial para instalar este servidor MCP

{
  "mcpServers": {
    "js-sandbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/var/run/docker.sock:/var/run/docker.sock",
        "alfonsograziano/node-code-sandbox-mcp"
      ]
    }
  }
}

Construir

Compilar y agrupar:

npm install
npm run build

Licencia

Licencia MIT

Por la presente se concede permiso, sin cargo, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el "Software"), para tratar el Software sin restricción, incluyendo, sin limitación, los derechos a usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir que las personas a quienes se les proporciona el Software lo hagan, sujeto a las siguientes condiciones:

El aviso de derechos de autor anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN DETERMINADO Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGUNA RECLAMACIÓN, DAÑOS U OTRAS RESPONSABILIDADES, YA SEA EN ACCIÓN CONTRACTUAL, EXTRACONTRACTUAL O DE OTRO TIPO, QUE SURJA DE, SE DERIVE DE O EN RELACIÓN CON EL SOFTWARE O EL USO U OTRAS RELACIONES CON EL MISMO.

Node.js Sandbox MCP Server

Integrations