Quickjs Sandbox

🚀 MCP QuickJS 運行器

MCP QuickJS 運行器是一個實現了 Model Context Protocol (MCP) 的服務器，它提供了一種安全的方式，能在 QuickJS 引擎中執行任意 JavaScript 代碼。該引擎通過 WebAssembly (WASM) 編譯，並藉助 Node.js 的內置 WASI 實現來運行，為語言模型或其他 MCP 客戶端提供了安全執行可能不受信任的 JavaScript 代碼片段的能力，且不會對主機系統造成風險。

🚀 快速開始

要啟動 MCP QuickJS 運行器，可使用以下命令：

node server.ts

✨ 主要特性

• 安全執行：藉助 QuickJS 和 Node.js WASI，在 WASM 砂箱中運行 JavaScript 代碼，保障執行過程的安全性。
• 標準 I/O 捕獲：能夠捕獲從 WASM 環境輸出的標準輸出（stdout）和標準錯誤（stderr）。
• 錯誤報告：可報告 QuickJS 運行時錯誤和非零退出碼，方便開發者及時排查問題。
• MCP 集成：通過標準輸入輸出（stdio）向 MCP 客戶端暴露標準功能，實現與 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 客戶端。

工作原理

1. WASM 模塊：使用預編譯的 QuickJS 引擎（qjs-wasi.wasm），該引擎針對 WebAssembly 系統接口 (WASI) 進行了目標編譯。
2. Node.js WASI：利用 Node.js 的 node:wasi 模塊來實例化和運行 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 請求，並按協議格式將執行結果返回給客戶端。