QuickJS Sandbox

🚀 MCP QuickJS 运行器

MCP QuickJS 运行器是一个实现了 Model Context Protocol (MCP) 的服务器，它提供了一种安全的方式，可在 QuickJS 引擎中执行任意 JavaScript 代码。该引擎通过 WebAssembly (WASM) 编译，并借助 Node.js 的内置 WASI 实现运行。

🚀 快速开始

若要启动 MCP QuickJS 运行器，可使用以下命令：

node server.ts

✨ 主要特性

• 安全执行：借助 QuickJS 和 Node.js WASI，在 WASM 砂箱中运行 JavaScript 代码，保障执行安全。
• 标准 I/O 捕获：能够捕获 WASM 环境输出的标准输出（stdout）和标准错误（stderr）。
• 错误报告：可报告 QuickJS 运行时错误和非零退出码。
• MCP 集成：通过标准输入输出（stdio）向 MCP 客户端暴露标准功能。
• 使用 TypeScript 开发：提供类型安全，确保开发过程的安全性。

📦 安装指南

先决条件

• Node.js（推荐 v23.x 或更高版本，具体取决于您使用的 node:wasi 的兼容性）
• npm 或 yarn
• 快速获取或编译 QuickJS WASM 文件 (qjs-wasi.wasm)。该文件必须位于服务器脚本所在的同一目录中（例如，相对于 ./dist/server.js 的 ./dist/qjs-wasi.wasm）。如果需要，请自行获取或编译。

安装步骤

1. 克隆仓库（如适用）。
2. 安装依赖：

npm install

📚 详细文档

描述

此服务器充当 MCP 工具提供者。它暴露一个名为 run_javascript_code 的工具，该工具接收一段 JavaScript 代码字符串作为输入。然后在 QuickJS WASM 环境中安全地执行这段代码。服务器捕获执行过程中的标准输出（stdout）和标准错误（stderr），并将这些结果连同任何运行时错误一并返回给 MCP 客户端。

这使语言模型或其他 MCP 客户端能够安全地执行可能不受信任的 JavaScript 代码片段，而不会对主机系统造成风险。

工作原理

1. WASM 模块：使用预编译的 QuickJS 引擎（qjs-wasi.wasm），该引擎针对 WebAssembly 系统接口 (WASI) 进行了目标编译。
2. Node.js WASI：利用 Node.js 的 node:wasi 模块来 Instantiate 和运行 WASM 模块。
3. Stdio 重定向（临时文件）：为了捕获 WASM 环境中的 stdout 和 stderr，当前的服务器实现依赖于与 node:wasi 兼容的标准方法：
   • 在主机文件系统上使用 node:fs/promises 和 node:os 创建一个临时目录。
   • 在该目录中打开 stdout 和 stderr 的临时文件。
   • 将 实际操作系统文件描述符 传递给 WASI 实例在初始化时（stdout: fd，stderr: fd）。
   • QuickJS WASM 模块将输出写入这些描述符，通过 WASI 路由到临时文件。
   • 执行完成后，服务器关闭文件句柄并读取临时文件的内容。
   • 清理临时目录和文件。 (注意：尝试使用内存管道或类似 memfs 的虚拟文件系统来代替临时文件的方法失败了，因为 node:wasi 目前需要实际的操作系统文件描述符来进行 stdio。)
4. MCP 通信：服务器使用 @modelcontextprotocol/sdk 通过 stdio 监听 MCP 请求，并按协议格式将执行结果返回给客户端。