Codesandbox MCP

🚀 CodeSandbox MCP Server

このサーバーは、CodeSandbox SDKの操作をAIエージェント用のツールとして公開する、Model Context Protocol (MCP) サーバーです。

• ランタイム: 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>: 作成/再開時のデフォルトのVM階層を設定します。
• --hibernation-timeout <seconds>: デフォルトの非アクティブ時の休止タイムアウトを設定します。
• --keep-alive: 接続中はセッションをアクティブに保ちます。
• --log-level <error|warn|info|debug>: ログレベルを設定します。

💻 使用例

基本的な使用法

全てのツールはステートレスです。サーバー管理のセッションレジストリはありません。各呼び出しは、提供された引数のみを使用してSDK操作を直接実行します。

• createSandbox

  • 説明: サンドボックスを作成します (オプションでテンプレート id から)、またオプションでカスタムVM設定で起動します。
  • パラメータ:
    • privacy (public|private): サンドボックスのプライバシー設定。
    • title (string): オプションのタイトル。
    • description (string): オプションの説明。
    • tags (string[]): 最大10個のタグ。
    • path (string): ワークスペース内の宛先フォルダパス。
    • id (string): フォーク元のテンプレートサンドボックスID。
    • ipcountry (string): VMスケジューリングのためのISO 3166-1 alpha-2国コードのヒント。
    • vmTier (string): VM階層 (例: Pico, Nano, ...)。サーバーのデフォルトを上書きします。
    • hibernationTimeoutSeconds (number): VMが休止するまでの非アクティブタイムアウト。
    • automaticWakeupConfig.http (boolean): HTTPで自動起動。
    • automaticWakeupConfig.websocket (boolean): WebSocketで自動起動。

• resumeSandbox

  • 説明: サンドボックスVMを再開 (または起動) します。
  • パラメータ:
    • sandboxId (string): 対象のサンドボックスID。

• hibernateSandbox

  • 説明: サンドボックスVMを休止させます (VMを保存してスリープさせます)。
  • パラメータ:
    • sandboxId (string): 対象のサンドボックスID。

• getSandboxInfo

  • 説明: VMを起動せずにサンドボックスのメタデータを取得します。
  • パラメータ:
    • sandboxId (string): 取得するサンドボックスID。

• updateSandbox

  • 説明: 実行中のサンドボックスのVM設定を更新します。
  • パラメータ:
    • sandboxId (string): 対象のサンドボックスID。
    • vmTier (string): VM階層を変更します (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のID/オプション。
      • 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: サンドボックスの作成、読み取り/編集、VM管理、プレビュートークン管理のスコープを持つPAT。

制限事項

• このサーバーはCodeSandboxのサンドボックス (VM) を対象としており、レガシープロジェクトでは使用できません。
• セッションの再開には sandbox.connect({ id: sessionId }) を使用します。