Codesandbox MCP

🚀 CodeSandbox MCP 服務器

這是一個模型上下文協議（MCP）服務器，它將 CodeSandbox SDK 操作作為工具暴露給 AI 代理。

• 運行環境：Node.js 18+
• 認證方式：CODESANDBOX_API_TOKEN（或 CSB_API_KEY）
• SDK：官方 @codesandbox/sdk

🚀 快速開始

安裝與運行

可以在 MCP 客戶端配置中通過 npx 使用該服務器。

示例（Cursor/Claude Desktop 的 mcp.json 片段）：

{
  "mcpServers": {
    "codesandbox": {
      "command": "npx",
      "args": [
        "-y",
        "@techlibs/codesandbox-mcp@latest",
        "--read-only"
      ],
      "env": {
        "CODESANDBOX_API_TOKEN": "<your-api-token>"
      }
    }
  }
}

CLI 二進制文件名稱：mcp-server-codesandbox

也可以直接運行：

npx -y @techlibs/codesandbox-mcp@latest --help

可用參數：

• --read-only：禁止使用修改工具（寫入/重命名），並將默認會話設置為只讀權限。
• --vm-tier <tier>：創建/恢復時的默認虛擬機層級。
• --hibernation-timeout <seconds>：默認的非活動休眠超時時間。
• --keep-alive：連接時保持會話活躍。
• --log-level <error|warn|info|debug>：日誌級別。

💻 使用示例

無狀態工具

所有工具都是無狀態的，即沒有服務器管理的會話註冊表。每次調用僅使用提供的參數直接執行 SDK 操作。

createSandbox

• 描述：創建一個沙箱（可選地從模板 id 創建），並可選擇使用自定義虛擬機設置啟動。
• 參數：
  • privacy (public|private)：沙箱的隱私設置。
  • title (string)：可選的標題。
  • description (string)：可選的描述。
  • tags (string[])：最多 10 個標籤。
  • path (string)：工作區內的目標文件夾路徑。
  • id (string)：要派生的模板沙箱 ID。
  • ipcountry (string)：用於虛擬機調度的 ISO 3166-1 alpha-2 國家提示。
  • vmTier (string)：虛擬機層級（例如 Pico、Nano 等），會覆蓋服務器默認設置。
  • hibernationTimeoutSeconds (number)：虛擬機休眠前的非活動超時時間。
  • automaticWakeupConfig.http (boolean)：HTTP 自動喚醒。
  • automaticWakeupConfig.websocket (boolean)：WebSocket 自動喚醒。

resumeSandbox

• 描述：恢復（或啟動）一個沙箱虛擬機。
• 參數：
  • sandboxId (string)：目標沙箱 ID。

hibernateSandbox

• 描述：使沙箱虛擬機進入休眠狀態（保存並暫停虛擬機）。
• 參數：
  • sandboxId (string)：目標沙箱 ID。

getSandboxInfo

• 描述：在不啟動虛擬機的情況下獲取沙箱元數據。
• 參數：
  • sandboxId (string)：要獲取的沙箱 ID。

updateSandbox

• 描述：更新正在運行的沙箱的虛擬機設置。
• 參數：
  • sandboxId (string)：目標沙箱 ID。
  • vmTier (string)：更改虛擬機層級（Pico|Nano|Micro|Small|Medium|Large|XLarge）。
  • hibernationTimeoutSeconds (number)：更新非活動休眠超時時間。

createSession

• 描述：為沙箱創建一個會話（服務器端不存儲狀態）。
• 參數：
  • sandboxId (string)：目標沙箱 ID。
  • sessionId (string, 可選)：提供特定的會話 ID；如果省略，則生成一個 UUID。
  • permission (read|write)：會話權限。使用 read 進行安全的、非修改性的訪問。
  • env (Record<string,string>, 可選)：會話的環境變量。
  • git (object, 可選)：會話創建時的 Git 身份/選項。
    • provider (string)：例如 "github"。
    • username (string, 可選)
    • accessToken (string, 可選)
    • email (string)
    • name (string, 可選)

resumeSession

• 描述：通過 sandboxId + sessionId 連接到現有會話。如果會話不存在，則使用可選參數創建。
• 參數：
  • sandboxId (string)：目標沙箱 ID。
  • sessionId (string)：要連接的會話標識符。
  • permission (read|write, 可選)：創建會話時使用。
  • env (Record<string,string>, 可選)：創建會話時使用。

readFile

• 描述：從沙箱文件系統中讀取文件。該工具每次調用時使用 sandboxId + sessionId 進行連接。
• 參數：
  • sandboxId (string)：目標沙箱 ID。
  • sessionId (string)：會話標識符（如果需要會創建）。
  • permission (read|write, 可選)：創建會話時使用。
  • env (Record<string,string>, 可選)：創建會話時使用。
  • path (string)：沙箱文件系統內的絕對路徑。
  • encoding (utf8|base64, 可選)：返回內容的編碼（默認 utf8）。

readdir

• 描述：列出給定路徑下的文件和目錄。該工具每次調用時使用 sandboxId + sessionId 進行連接。
• 參數：
  • sandboxId (string)：目標沙箱 ID。
  • sessionId (string)：會話標識符（如果需要會創建）。
  • permission (read|write, 可選)：創建會話時使用（只讀模式下默認為 read）。
  • env (Record<string,string>, 可選)：創建會話時使用。
  • path (string)：沙箱文件系統內要列出的絕對路徑。

writeFile

• 描述：在沙箱文件系統中寫入文件。該工具每次調用時使用 sandboxId + sessionId 進行連接。
• 參數：
  • sandboxId (string)：目標沙箱 ID。
  • sessionId (string)：會話標識符（如果需要會創建），必須允許寫入。
  • permission (read|write, 可選)：創建會話時使用（通常為 write）。
  • env (Record<string,string>, 可選)：創建會話時使用。
  • path (string)：文件的絕對路徑。
  • content (string)：要寫入的內容（根據 encoding 編碼）。
  • encoding (utf8|base64, 可選)：內容編碼（默認 utf8）。
  • overwrite (boolean, 可選)：覆蓋現有文件（默認 true）。
  • create (boolean, 可選)：如果文件不存在則創建（默認 true）。

rename

• 描述：重命名/移動文件或目錄。該工具每次調用時使用 sandboxId + sessionId 進行連接。
• 參數：
  • sandboxId (string)：目標沙箱 ID。
  • sessionId (string)：會話標識符（如果需要會創建），必須允許寫入。
  • permission (read|write, 可選)：創建會話時使用（通常為 write）。
  • env (Record<string,string>, 可選)：創建會話時使用。
  • from (string)：源路徑。
  • to (string)：目標路徑。
  • overwrite (boolean, 可選)：如果目標存在則覆蓋（默認 true）。

注意事項

• 文件系統操作在調用期間連接 SandboxClient 並立即釋放，不保留狀態。
• 輸出以文本塊形式返回（JSON 有效負載序列化為字符串），以實現廣泛的客戶端兼容性。

🔧 開發

• 構建：npm run build
• 開發（標準輸入輸出）：npm run dev（需要設置令牌環境變量）

📚 環境變量

• CODESANDBOX_API_TOKEN（首選）或 CSB_API_KEY：具有沙箱創建、讀取/編輯、虛擬機管理、預覽令牌管理權限的個人訪問令牌（PAT）。

⚠️ 限制

• 此服務器針對 CodeSandbox 沙箱（虛擬機），而非舊版項目。
• 會話恢復使用 sandbox.connect({ id: sessionId })。