关键词

代码执行Docker 容器LLM Agent代码修改项目管理

使用说明

项目简介

Codebox 是一个专为 LLM Agent 设计的 Model Context Protocol (MCP) 服务器，旨在安全地进行代码变更操作。它通过 Docker 容器隔离执行命令，并限制文件系统访问在注册的项目目录内，为 LLM Agent 提供了一个安全可控的代码操作环境。

主要功能点

  • 隔离的代码执行环境: 所有命令都在隔离的 Docker 容器中执行，确保宿主机环境的安全。
  • 项目级文件操作: 文件操作被限制在预先注册的项目目录内，防止 LLM Agent 意外修改系统文件。
  • 细粒度的工具控制: 提供一系列工具如命令执行、文件读写、项目管理等，允许 LLM Agent 通过调用工具完成代码相关的任务。
  • 灵活的配置系统: 支持项目级别和系统级别的 Docker 镜像配置，方便用户根据不同项目需求进行定制。
  • 支持批量操作: 提供批量命令执行和批量文件写入工具，提高 LLM Agent 的操作效率，并减少 API 调用次数。

安装步骤

  1. 安装 Node.js 和 npm: 确保你的系统已安装 Node.js (v16+) 和 npm。
  2. 安装 Docker: 确保 Docker 守护进程正在运行。
  3. 安装 Git: 确保已安装 Git。
  4. 全局安装 Codebox: 运行以下命令全局安装 Codebox： 
    npm install -g @codespin/codebox

服务器配置

MCP 客户端需要配置 Codebox 服务器的启动命令才能连接并使用其功能。以下是推荐的配置信息（JSON 格式）：

{
  "serverName": "codebox",
  "command": "codebox",
  "args": ["start"]
}

配置参数说明:

  • 'serverName': 服务器名称，可以自定义，例如 "codebox"。
  • 'command': 启动 Codebox 服务器的命令，这里使用全局安装后的 'codebox' 命令。
  • 'args': 传递给 'codebox' 命令的参数，'start' 参数指示 Codebox 启动 MCP 服务器。

注意: MCP 客户端需要确保可以执行 'codebox' 命令。如果全局安装后 'codebox' 命令不在 PATH 环境变量中，请根据你的系统环境进行配置，或者使用 'npm prefix -g' 找到全局安装目录，并使用绝对路径来配置 'command'。

基本使用方法

  1. 初始化项目 (可选): 如果你的项目还没有配置 Codebox，可以使用 'codebox init' 命令进行初始化，并指定 Docker 镜像。例如，使用 Node.js 18 镜像初始化项目：

    cd your-project-directory
codebox init --image node:18

    也可以设置系统级别的默认 Docker 镜像：

    codebox init --system --image node:18

  2. 注册项目: 使用 'codebox project add' 命令注册你想要操作的项目目录。例如，注册当前目录：

    codebox project add $(pwd)

  3. 启动 MCP 服务器: 运行 'codebox start' 命令启动 MCP 服务器。

    codebox start

    服务器启动后，会监听来自 MCP 客户端的请求。

  4. 在 MCP 客户端中使用: 在你的 MCP 客户端中，配置连接到 Codebox 服务器，并可以使用 'list_projects', 'execute_command', 'write_file' 等工具来操作已注册的项目。 具体工具的使用方法请参考仓库 README.md 中 "MCP Tools" 部分的描述和参数定义。

示例工作流程 (LLM Agent 端)

LLM Agent 可以通过以下步骤与 Codebox 服务器交互，完成代码修改任务：

  1. 列出可用项目: 调用 'list_projects' 工具查看已注册的项目列表和状态。
  2. 执行命令: 使用 'execute_command' 工具在指定项目的 Docker 容器中执行命令，例如查看目录内容 'ls src'。
  3. 读取文件 (谨慎): 可以使用 'execute_command' 工具结合 'head', 'tail', 'cat' 等命令读取文件内容，但需要注意控制 token 使用量，避免读取过大的文件。 建议先使用 'ls -l' 或 'wc -c' 等命令查看文件大小，再决定是否读取完整内容。
  4. 修改文件: 使用 'write_file' 或 'write_batch_files' 工具修改或创建文件。
  5. 批量执行命令: 使用 'execute_batch_commands' 工具批量执行命令，例如安装依赖和运行测试 'npm install && npm test'。

重要提示: 请仔细阅读 README.md 中 "Agent Prompt" 和 "TOKEN USAGE WARNING" 部分，了解如何高效安全地使用 Codebox 工具，避免 token 浪费和潜在风险。

信息

分类

开发者工具

访问项目