Quickjs Sandbox

🚀 MCP QuickJS Runner

A server implementing the Model Context Protocol (MCP), providing a tool to securely execute arbitrary JavaScript code in the QuickJS engine. This engine is compiled via WebAssembly (WASM) and runs using Node.js's built-in WASI implementation.

🚀 Quick Start

To start using the MCP QuickJS Runner, follow these steps:

node server.ts

✨ Features

• Secure Execution: Run JavaScript in a WASM sandbox using QuickJS and Node.js WASI.
• Standard I/O Capture: Capture stdout and stderr output from the WASM environment.
• Error Reporting: Report QuickJS runtime errors and non-zero exit codes.
• MCP Integration: Expose standard functions to MCP clients via stdio.
• Developed with TypeScript: Provide type safety to ensure security during development.

📚 Documentation

Description

This server acts as an MCP tool provider. It exposes a tool named run_javascript_code, which takes a string of JavaScript code as input. Then, it securely executes this code in the QuickJS WASM environment. The server captures the standard output (stdout) and standard error (stderr) during execution and returns these results, along with any runtime errors, to the MCP client.

This enables language models or other MCP clients to securely execute potentially untrusted JavaScript code snippets without risking the host system.

How It Works

1. WASM Module: Use the pre-compiled QuickJS engine (qjs-wasi.wasm), which is targeted for the WebAssembly System Interface (WASI).
2. Node.js WASI: Leverage Node.js's node:wasi module to instantiate and run the WASM module.
3. Stdio Redirection (Temporary Files): To capture stdout and stderr in the WASM environment, the current server implementation relies on a standard method compatible with node:wasi:
   • Use node:fs/promises and node:os to create a temporary directory on the host file system.
   • Open temporary files for stdout and stderr in that directory.
   • Pass the actual operating system file descriptors to the WASI instance during initialization (stdout: fd, stderr: fd).
   • The QuickJS WASM module writes output to these descriptors, which are routed to the temporary files via WASI.
   • After execution, the server closes the file handles and reads the contents of the temporary files.
   • Clean up the temporary directory and files. (Note: Attempts to use in-memory pipes or virtual file systems like memfs instead of temporary files failed because node:wasi currently requires actual operating system file descriptors for stdio.)
4. MCP Communication: The server uses @modelcontextprotocol/sdk to listen for MCP requests via stdio and returns the execution results to the client in the protocol format.

📦 Installation

1. Clone the repository (if applicable).
2. Install dependencies:

npm install

🔧 Prerequisites

• Node.js (Recommended v23.x or higher, depending on the compatibility of the node:wasi you use).
• npm or yarn.
• Obtain or compile the QuickJS WASM file (qjs-wasi.wasm) quickly. This file must be in the same directory as the server script (e.g., ./dist/qjs-wasi.wasm relative to ./dist/server.js). Obtain or compile it yourself if necessary.