JinDaGe - codesandbox-mcp MCP Details

article

README

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

codesandbox-mcp