CodeBox-AI

CodeBox-AI

OpenAI の Code Interpreter や Anthropic の Claude analysis tool に代わるセルフホスト可能なサービスとして、安全な Python コード実行環境を提供します。FastAPI と IPython カーネルを使用して構築されており、セッションベースのコード実行に対応し、LLM の関数呼び出しと連携します。

また、LLM アプリケーションとシームレスに連携できるよう、Model Context Protocol（MCP）にも対応しました。

機能

• Docker コンテナでのセッションベースの Python コード実行
• リッチ出力に対応した IPython カーネル
• セキュリティ制御付きの動的なパッケージインストール
  • パッケージの許可リスト／ブロックリストシステム
  • セキュリティ脆弱性に対応したバージョン管理
  • pip と conda によるインストールに対応
• 実行間での状態の永続化
• プロットと可視化に対応
• コードのセキュリティ検証
  • AST ベースのコード分析
  • 危険なインポートや操作からの保護
  • Jupyter マジックコマンドとシェル操作に対応
• ホストディレクトリのマウント
  • ローカルディレクトリをコンテナにマウント
  • 読み取り専用または読み書き可能なアクセス制御
  • 機密性の高いパスへのアクセスを防ぐセキュリティ検証

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 の「file not found」エラー

MacOS でサーバーを実行中に「file not found」という 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 - 詳細は LICENSE ファイルをご覧ください。

作者について

このコードは Claude 3.5 Sonnet とペアプログラミングして作成しました（そう、AI がほかの AI 向けのツール作りを手伝っています。実にメタですね）。プロダクトの意思決定とアーキテクチャのレビューは私が担当し、コード生成とドキュメント作成の大部分は Claude が担いました。この README も Claude が書いたので、AI が AI ツールについて書く AI について語るような、少し不思議な状況です……さらに深掘りしていきましょう 🤖✨

開発プロセスには、（ほとんどの場合）人間も参加していました。このプロジェクトの作成中に AI が傷つくことはありませんでしたが、再帰に目が回ってしまった AI はいたかもしれません。

---

プロトタイプ実装です。追加のセキュリティ対策を講じずに本番環境で使用することを意図したものではありません。