使用说明

项目简介

Codebox 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为 AI 助手（如 LibreChat、Claude Desktop）提供代码执行和工作区管理能力。它允许 AI 助手在隔离的 Docker 容器环境中安全地运行命令，并对容器内的文件进行读写操作，从而扩展了 AI 助手的交互能力，使其能够处理代码相关的任务。

主要功能点

工作区管理: 可以注册、列出和移除工作区。每个工作区关联一个目录和一个 Docker 镜像或容器，用于隔离不同的项目环境。
容器化执行环境: 在 Docker 容器中运行命令，确保执行环境的可复现性和隔离性。
文件系统操作: 允许 AI 助手在工作区容器中读写文件，支持覆盖和追加模式。
批量操作: 支持批量执行命令和批量文件写入，提高效率。
复制模式: 工作区可以配置为“复制模式”，在容器中操作的是工作区文件的一个临时副本，保护原始文件不被修改。
MCP 协议支持: 实现了 Model Context Protocol，可以通过标准的 JSON-RPC 协议与 MCP 客户端通信。
Stdio 传输: 使用 Stdio 作为默认的传输协议，方便集成到各种 MCP 客户端。
详细日志: 支持debug模式，记录详细的 MCP 调用日志，方便问题排查。

安装步骤

确保已安装 Node.js 和 npm。
确保已安装 Docker 并正在运行。

打开终端，运行以下命令全局安装 Codebox：

npm install -g @codespin/codebox

服务器配置

要将 Codebox 作为 MCP 服务器配置到 MCP 客户端（例如 LibreChat），您需要提供以下配置信息。以下是 LibreChat 的配置示例，其他 MCP 客户端的配置方式类似，请参考各自客户端的文档进行配置。

{
  "mcpServers": {
    "codebox": {
      "type": "stdio",
      "command": "codebox",
      "args": ["start"],
      "timeout": 30000,
      "initTimeout": 10000
    }
  }
}

配置参数说明:

server name: 'codebox' - 服务器名称，可以自定义，用于在 MCP 客户端中标识该服务器。
type: 'stdio' - 传输协议类型，Codebox 使用标准输入输出流 (stdio) 进行通信。
command: 'codebox' - 启动 Codebox 服务器的命令。确保 'codebox' 命令在您的系统 PATH 环境变量中，或者使用 Codebox 可执行文件的完整路径。
args: '["start"]' - 传递给 'codebox start' 命令的参数，用于启动服务器。
timeout: '30000' - 命令执行超时时间，单位毫秒。这里设置为 30 秒。
initTimeout: '10000' - 服务器初始化超时时间，单位毫秒。这里设置为 10 秒。

基本使用方法

启动 Codebox 服务器: 在终端中运行 'codebox start' 命令，启动 MCP 服务器。
配置工作区: 使用 'codebox workspace add' 命令注册工作区。例如，要将当前目录注册为一个名为 'my-workspace'，使用 'node:18' 镜像的工作区，可以运行：
```
codebox workspace add --image node:18 --name my-workspace
```
更多 'codebox workspace add' 命令的选项，请参考仓库 README 或运行 'codebox workspace add --help'。
在 AI 助手中使用: 在配置好 MCP 服务器的 AI 助手（如 LibreChat）中，您可以使用 'list_workspaces' 工具列出已注册的工作区，使用 'open_workspace' 打开工作区，获取 workspace token，然后使用 'execute_command', 'execute_batch_commands', 'write_file', 'write_batch_files' 等工具，并带上 workspace token 在指定的工作区中执行命令和操作文件。使用完毕后，使用 'close_workspace' 关闭工作区。

示例工作流程 (LibreChat):

在 LibreChat 中，您可以指示 AI 助手执行以下操作：

"列出所有可用的工作区" (对应 'list_workspaces' 工具)
"打开名为 my-workspace 的工作区" (对应 'open_workspace' 工具，获取 workspace token)
"在工作区中执行命令 'node -v'" (对应 'execute_command' 工具，带上 workspace token)
"在工作区中创建一个名为 test.js 的文件，内容为 'console.log('Hello Codebox!')'" (对应 'write_file' 工具，带上 workspace token)
"在工作区中执行命令 'node test.js'" (对应 'execute_command' 工具，带上 workspace token)
"关闭当前工作区" (对应 'close_workspace' 工具，带上 workspace token)

通过以上步骤，您就可以利用 Codebox 为 AI 助手提供代码执行和工作区管理能力。

关键词