CodeBox-AI

CodeBox-AI

一个安全的 Python 代码执行服务，可作为 OpenAI Code Interpreter 或 Anthropic 的 Claude analysis tool 的可自托管替代方案。它基于 FastAPI 和 IPython 内核构建，支持基于会话的代码执行，并可集成 LLM 函数调用。

现在还支持 Model Context Protocol（MCP），可与 LLM 应用无缝集成。

功能

• 在 Docker 容器中执行基于会话的 Python 代码
• 使用 IPython 内核支持丰富的输出
• 动态安装软件包，并提供安全控制
  • 软件包允许列表／阻止列表系统
  • 通过版本控制防范安全漏洞
  • 支持通过 pip 和 conda 安装
• 在多次执行之间持久保存状态
• 支持绘图和可视化
• 代码安全验证
  • 基于 AST 的代码分析
  • 防范危险的导入和操作
  • 支持 Jupyter 魔法命令和 Shell 操作
• 挂载主机目录
  • 将本地目录挂载到容器中
  • 控制只读或读写访问权限
  • 通过安全验证防止访问敏感路径

MCP 服务（Model Context Protocol）

CodeBox-AI 现在支持 Model Context Protocol（MCP），让 LLM 应用（例如 Claude Desktop）可以通过标准化方式与代码执行服务交互。

运行 MCP 服务

你可以通过多种方式运行 MCP 服务：

• 独立运行（供 MCP 客户端或 Claude Desktop 使用）：

  uv run mcp dev mcp_server.py
  

  这会以开发模式启动 MCP 服务，用于本地测试和调试。

• 注册到 Claude Desktop：

  uv run mcp install mcp_server.py --name "CodeBox-AI"
  

  这样，Claude Desktop 就可以将你的服务作为自定义工具使用。

• 同时运行 FastAPI 和 MCP 服务：

  uv run run.py
  

  这会同时启动 FastAPI API 和 MCP 服务（MCP 可通过 /mcp 访问）。

• 仅运行 MCP 服务：

  uv run run.py --mode mcp
  

MCP 功能

• execute_code：执行 Python 代码并返回结果
• session://{session_id}：获取会话信息
• sessions://：列出所有活跃会话

示例：使用 MCP Inspector 测试

1. 启动 MCP 服务：

   uv run mcp dev mcp_server.py
   

2. 打开 MCP Inspector，并连接到本地服务。

示例：注册到 Claude Desktop

1. 在 Claude Desktop 设置中配置 MCP 服务：

编辑文件 ~/Library/Application Support/Claude/claude_desktop_config.json。以下是一个配置示例：

{
  "mcpServers": {
    "CodeBox-AI": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/Users/username/src/codebox-ai",
        "/Users/username/src/codebox-ai/mcp_server.py",
        "--mount",
        "/Users/username/Downloads"
      ]
    }
  }
}

遗憾的是，所有路径都必须是绝对路径。此示例展示了如何将 Downloads 目录挂载到容器中。

2. 打开 Claude Desktop，服务应会作为自定义工具显示。

前置条件

• Python 3.9+
• Docker
• uv - 快速的 Python 软件包安装器和解析器

安装

1. 克隆仓库：

git clone https://github.com/yourusername/codebox-ai.git
cd codebox-ai

2. 使用 uv 安装依赖：

# Install uv if you don't have it yet
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment and install dependencies in one step
uv sync

3. 启动服务：

uv run -m codeboxai.main

API 可通过 http://localhost:8000 访问。

开发环境设置

进行开发时，请安装包含开发附加依赖的版本：

uv sync --extra "dev docs"

Docker“找不到文件”错误

如果在 MacOS 上运行服务时遇到“找不到文件”的 DockerException，可能需要设置 DOCKER_HOST 环境变量。首先，运行以下命令查看当前使用的上下文：

docker context ls

然后将 DOCKER_HOST 环境变量设置为正确的端点：

export DOCKER_HOST="unix:///Users/tconte/.docker/run/docker.sock"

使用方法

示例：集成 OpenAI GPT

1. 在项目根目录中创建 .env 文件：

AZURE_OPENAI_ENDPOINT=https://xxx.cognitiveservices.azure.com/
AZURE_OPENAI_API_KEY=foo
AZURE_OPENAI_DEPLOYMENT=gpt-4o
OPENAI_API_VERSION=2024-05-01-preview

2. 安装额外依赖：

uv sync --extra "examples"

3. 运行示例：

uv run examples/example_openai.py

这会启动一个交互式会话，你可以在其中与 GPT-4 聊天，并让它执行 Python 代码。脚本会在多次执行之间保持状态，因此变量和导入内容会在交互过程中保留。

如果要向容器开放本地目录，可以使用 CODEBOX_MOUNT_PATH 环境变量。例如，要挂载 Downloads 目录：

export CODEBOX_MOUNT_PATH=/Users/username/Downloads
uv run examples/example_openai.py

直接使用 API

1. 创建一个新会话：

curl -X POST http://localhost:8000/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "dependencies": ["numpy", "pandas"]
  }'

2. 在会话中执行代码：

curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -d '{
    "code": "x = 42\nprint(f\"Value of x: {x}\")",
    "session_id": "YOUR_SESSION_ID"
  }'

3. 检查执行状态：

curl -X GET http://localhost:8000/execute/YOUR_REQUEST_ID/status

4. 获取执行结果：

curl -X GET http://localhost:8000/execute/YOUR_REQUEST_ID/results

5. 在同一会话中执行更多代码：

curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(f\"x is still: {x}\")",
    "session_id": "YOUR_SESSION_ID"
  }'

6. 创建一个挂载目录的会话：

curl -X POST http://localhost:8000/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "execution_options": {
      "mount_points": [
        {
          "host_path": "/Users/tconte/Downloads",
          "container_path": "/data/downloads",
          "read_only": true
        }
      ],
      "timeout": 300
    }
  }'

7. 执行访问挂载文件的代码：

curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import os\nprint(\"Files in mounted directory:\")\nfor file in os.listdir(\"/data/downloads\"):\n    print(f\" - {file}\")",
    "session_id": "YOUR_SESSION_ID"
  }'

API 端点

• POST /sessions - 创建一个新会话
• POST /execute - 在会话中执行代码
• GET /execute/{request_id}/status - 获取执行状态
• GET /execute/{request_id}/results - 获取执行结果
• DELETE /sessions/{session_id} - 清理会话

安全说明

• 使用 Docker 将代码执行容器化
• 每个会话都在隔离环境中运行
• 已实施基本资源限制
• 可使用网络访问，但也可以限制
• 已实施输入代码验证，以保障基本安全

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

关于作者的一点说明

这份代码是与 Claude 3.5 Sonnet 结对编程完成的（没错，AI 正在帮助构建供其他 AI 使用的工具——真是元极了）。我负责产品决策和架构评审，而 Claude 承担了大部分代码生成和文档编写工作。甚至这份 README 也是 Claude 写的，这让这段致谢有点像是 AI 在写一段关于 AI 撰写 AI 工具的内容……我们得继续深入下去 🤖✨

开发过程中，（大多数时候）都有人类在场。这个项目的制作过程中没有伤害任何 AI，不过可能有几个 AI 因为递归而稍微有点晕。

---

这是一个原型实现，若不采取额外的安全措施，不适合用于生产环境。