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 })。