devcontainer-mcp

devcontainer-mcp

AI エージェントに、あなたの環境ではなく専用の開発環境を。

devcontainer-mcp は、AI コーディングエージェントが dev コンテナ をローカル Docker、DevPod、GitHub Codespaces の 3 つのバックエンドで作成、管理、および内部での作業を行えるようにする MCP サーバーです。エージェントは隔離されたコンテナ内でコードをビルド、テスト、出荷するため、あなたのノート PC はクリーンなままです。

GitHub Copilot、Claude、Cursor、opencode、および MCP 互換のあらゆるクライアントで動作します。

課題

AI エージェントがコードを書くとき、それをどこかで実行する必要があります。現状、それはあなたのホストマシンを意味します:

• 🔴 ホストの汚染 — エージェントがパッケージをインストールし、PATH を変更し、ビルド成果物を残していく
• 🔴 「自分のマシンでは動く」 — エージェントはローカルのツールチェーンが本番環境と一致していると仮定する
• 🔴 隔離の欠如 — あるプロジェクトの依存関係が別のプロジェクトを壊す
• 🔴 セキュリティリスク — エージェントがあなたのユーザー権限で任意のコマンドを実行する
• 🔴 ハードウェアの制約 — ローカルマシンのリソースに縛られる

解決策

devcontainer 仕様 は、再現可能なコンテナベースの開発環境をすでに定義しています。主要なプロジェクトはすべて .devcontainer/devcontainer.json を同梱しています。しかし、AI エージェントはこれらを利用できませんでした — 今までは。

devcontainer-mcp は 45 個の MCP ツール を公開し、あらゆる AI エージェントが次のことを行えるようにします:

1. 任意のリポジトリから dev コンテナを 起動する — ローカル、クラウド VM、または Codespaces 上で
2. コンテナ内で コマンドを実行する — ビルド、テスト、リンティング、その他何でも
3. ライフサイクルを管理する — 完了したら停止、再起動、削除
4. クラウドプロバイダー — GitHub、AWS、Azure、GCP — に対して 認証する — 生のトークンを一切見せることなく

Agent: "Let me build this project..."
  → auth_status("github") → picks account
  → codespaces_create(auth: "github-you", repo: "your/repo")
  → codespaces_ssh(auth: "github-you", codespace: "...", command: "cargo build")
  → ✅ Built in the cloud. Your laptop did nothing.

クイックインストール

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/aniongithub/devcontainer-mcp/main/install.sh | bash

Windows (WSL 経由)

Invoke-RestMethod https://github.com/aniongithub/devcontainer-mcp/releases/latest/download/install.ps1 | Invoke-Expression

仕組み: バイナリは WSL 内で実行され、Windows 上の MCP クライアントは wsl ~/.local/bin/devcontainer-mcp serve を介して起動します。stdio トランスポートは WSL の境界を透過的に越えて動作します。WSL 2 が必要です — まだインストールしていない場合は wsl --install でインストールしてください。

バックエンド CLI (devpod、devcontainer、gh) は実行時に検出されます — いずれかが見つからない場合、MCP サーバーはインストール手順を含む役立つエラーを返します。

バイナリは linux-x64、linux-arm64、darwin-x64、darwin-arm64 向けに提供されています。

ホストの保護とオプトアウト

インストーラーは 2 つのエージェントフック (Claude Code および GitHub Copilot CLI) を構成し、これらは .devcontainer/devcontainer.json を含むディレクトリでのみ有効になります:

• devcontainer-guard (PreToolUse) — ホスト上でのシェル/コマンド実行をブロックし、エージェントがビルド、テスト、実行を代わりに MCP ツール経由でルーティングするようにします。ホストで安全なコマンド (git、gh) は許可リストに登録されており、両方のフックは フェイルオープン します — jq が見つからない場合やペイロードを解析できない場合、コマンドはブロックされるのではなく許可されます。
• devcontainer-skill-loader (SessionStart) — SKILL.md の使用ガイドをコンテキストとして注入します。

リポジトリ単位で無効化する

プロジェクトに古くなった、あるいはメンテナンスされていない .devcontainer が含まれていて、実際にはその経由で作業をルーティングしたくない場合があります。そのリポジトリで両方のフックを無効化するには、リポジトリのルートにマーカーファイルを置きます:

touch .devcontainer-mcp-disable

.devcontainer-mcp-disable が存在する場合、ガードはホストコマンドの通過を許可し、スキルローダーはコンテキスト注入をスキップします — エージェントは devcontainer が宣言されていないかのようにローカルで動作します。これをコミットしてください（ローカル限定でオプトアウトする場合は .gitignore に追加してください）。

一時的なバイパス: ガードを無効化せずに単一のホストコマンドを実行するには、コマンド内の任意の場所に USER_CONFIRMED_HOST_OPERATION=1 を含めます。

アーキテクチャ

graph TD
    A[AI Agent / MCP Client] -->|stdio JSON-RPC| B[devcontainer-mcp]
    
    subgraph "devcontainer-mcp"
        B --> C[33 MCP Tools]
        C --> D[Auth Broker]
        C --> E[devcontainer-mcp-core]
    end
    
    D -->|opaque handles| C
    E -->|subprocess| F[DevPod CLI]
    E -->|subprocess| G[devcontainer CLI]
    E -->|subprocess| H[gh CLI]
    E -->|bollard API| I[Docker Engine]
    
    F --> J[Docker / K8s / Cloud VMs]
    G --> K[Local Docker]
    H --> L[GitHub Codespaces]

3 つのバックエンド、1 つのインターフェース

バックエンド	最適な用途	必要なもの	認証が必要?
devcontainer CLI (devcontainer_*)	ローカル Docker — 高速でシンプル	@devcontainers/cli + Docker	いいえ
DevPod (devpod_*)	マルチクラウド: Docker、K8s、AWS、Azure、GCP	DevPod CLI	任意（クラウドプロバイダー）
Codespaces (codespaces_*)	GitHub がホストするクラウド環境	gh CLI	はい（auth ハンドル）

認証ブローカー

エージェントが生のトークンを目にすることはありません。代わりに:

1. auth_status(provider) — 利用可能なアカウントとスコープを一覧表示します
2. auth_login(provider, scopes?) — ログインを開始し、ブラウザーを開き、デバイスコードを処理します
3. auth_select(id) — アクティブなアカウントを切り替えます
4. auth_logout(id) — 認証情報を失効させます

Codespaces ツールには認証ハンドル（例: "github-aniongithub"）が必要です。MCP サーバーは、各呼び出し時に CLI ネイティブのキーリングを介してそれを実際のトークンに解決します。

対応プロバイダー: GitHub、AWS、Azure、GCP、Kubernetes

MCP ツール（合計 46 個）

認証（4 ツール）

ツール	説明
auth_status	プロバイダーの認証を確認します — ハンドル、アカウント、スコープを返します
auth_login	ログインまたはスコープの更新を開始します — ブラウザー + デバイスコードフロー
auth_select	プロバイダーのアクティブなアカウントを切り替えます
auth_logout	アカウントの認証情報を失効させます

DevPod（19 ツール）

ツール	説明
devpod_up	git URL、ローカルパス、またはイメージからワークスペースを作成して起動します
devpod_stop	実行中のワークスペースを停止します
devpod_delete	ワークスペースとそのリソースを削除します
devpod_build	起動せずにワークスペースイメージをビルドします
devpod_status	ワークスペースの状態（Running、Stopped、Busy、NotFound）を取得します
devpod_list	すべてのワークスペースを ID、ソース、プロバイダー、ステータスとともに一覧表示します
devpod_ssh	SSH 経由でワークスペース内のコマンドを実行します
devpod_logs	ワークスペースのログを取得します
devpod_provider_list	設定済みのすべてのプロバイダーを一覧表示します
devpod_provider_add	新しいプロバイダーを追加します
devpod_provider_delete	プロバイダーを削除します
devpod_context_list	すべてのコンテキストを一覧表示します
devpod_context_use	別のコンテキストに切り替えます
devpod_container_inspect	Docker inspect — ラベル、ポート、マウント、状態
devpod_container_logs	Docker API 経由でコンテナログをストリーミングします
devpod_file_read	オプションの行範囲を指定してファイル内容を読み取ります
devpod_file_write	ファイルを作成または上書きします（親ディレクトリを自動的に作成します）
devpod_file_edit	ピンポイントな文字列置換 — old_str → new_str
devpod_file_list	ディレクトリの内容を一覧表示します（非隠し、2 階層の深さ）

devcontainer CLI (12 ツール)

ツール	説明
devcontainer_up	ローカルの dev コンテナを作成して起動します
devcontainer_exec	実行中の dev コンテナ内でコマンドを実行します
devcontainer_build	dev コンテナイメージをビルドします
devcontainer_read_config	マージされた devcontainer 設定を JSON として読み取ります
devcontainer_list_configs	ワークスペース内のすべての devcontainer.json ファイルを検出します (シングル + マルチコンテナ)
devcontainer_stop	dev コンテナを停止します (Docker API 経由)
devcontainer_remove	dev コンテナとそのリソースを削除します
devcontainer_status	ワークスペースフォルダーごとに dev コンテナの状態を取得します
devcontainer_file_read	オプションの行範囲を指定してファイルの内容を読み取ります
devcontainer_file_write	ファイルを作成または上書きします (親ディレクトリを自動的に作成)
devcontainer_file_edit	部分的な文字列置換 — old_str → new_str
devcontainer_file_list	ディレクトリの内容を一覧表示します (非表示を除く、深さ 2 レベル)

GitHub Codespaces (11 ツール) — auth ハンドルが必要

ツール	説明
codespaces_create	リポジトリ用の新しい codespace を作成します
codespaces_list	状態とマシン情報を含む codespace の一覧を表示します
codespaces_ssh	SSH 経由で codespace 内のコマンドを実行します
codespaces_stop	実行中の codespace を停止します
codespaces_delete	codespace を削除します
codespaces_view	codespace の詳細情報 (状態、マシン、設定) を表示します
codespaces_ports	公開範囲と URL を含む転送ポートを一覧表示します
codespaces_file_read	オプションの行範囲を指定してファイルの内容を読み取ります
codespaces_file_write	ファイルを作成または上書きします (親ディレクトリを自動的に作成)
codespaces_file_edit	部分的な文字列置換 — old_str → new_str
codespaces_file_list	ディレクトリの内容を一覧表示します (非表示を除く、深さ 2 レベル)

MCP サーバーの設定

Linux / macOS

{
  "mcpServers": {
    "devcontainer-mcp": {
      "command": "devcontainer-mcp",
      "args": ["serve"]
    }
  }
}

Windows (WSL ブリッジ)

{
  "mcpServers": {
    "devcontainer-mcp": {
      "command": "wsl",
      "args": ["~/.local/bin/devcontainer-mcp", "serve"]
    }
  }
}

前提条件

必要に応じてバックエンド CLI をインストールしてください — MCP サーバーは実行時にそれらを検出し、見つからない場合は役立つエラーを返します:

• devcontainer CLI: npm install -g @devcontainers/cli + Docker
• DevPod: DevPod CLI + Docker (または別のプロバイダー)
• Codespaces: GitHub CLI — 認証は auth_login ツールによって処理されます

自己修復

devcontainer_up、devpod_up、または codespaces_create が失敗すると、完全なビルド出力 (エラーを含む) がエージェントに返されます。エージェントはエラーを読み取り、Dockerfile または devcontainer.json を修正して再試行できます — これにより、開発環境は静的な前提条件ではなく、動的でエージェントが管理する資産になります。

マルチコンテナワークスペース

devcontainer 仕様は、サービスごとの設定を .devcontainer/<name>/devcontainer.json に配置し、それぞれが共有の docker-compose.yml を指すことで、1 つのワークスペースで複数のコンテナに接続することをサポートしています。devcontainer-mcp はこのパターンをエンドツーエンドでサポートします:

• 検出 — devcontainer_list_configs は、検出したすべての設定(ルートの .devcontainer.json、.devcontainer/devcontainer.json、および各 .devcontainer/*/devcontainer.json)を、その種類(image / dockerfile / compose)、サービス名、絶対パスとともに返します。
• ターゲット指定 — すべての devcontainer ツール(up、exec、build、stop、remove、status、read_config、file_*)は、特定の devcontainer.json を指すオプションの config パラメータを受け付けます。シングルコンテナのワークフローはこれまでどおり動作します — config は、devcontainer CLI が自動検出するものにデフォルト設定されます。
• 曖昧さの処理 — ワークスペースに複数の設定があり、config が指定されていない場合、検索系のツール(status、exec、stop、remove、file_*)は、一致するすべてのコンテナを列挙した構造化された Ambiguous 結果を返すので、エージェントは適切なものを選択できます。status はこれを {"state":"Ambiguous","candidates":[...],"hint":"..."} として報告します。
• 堅牢なコンテナマッチング — 兄弟 compose コンテナは、com.docker.compose.service + com.docker.compose.project.config_files を介して識別されます(最初のコンテナにしか付与されない、信頼性の低い devcontainer.local_folder ラベルではありません)。

開発

このプロジェクトは自身のドッグフーディングを行っています — 開発は自身の devcontainer 内で行われます。

# Using the devcontainer CLI
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . cargo build --workspace
devcontainer exec --workspace-folder . cargo test --workspace
devcontainer exec --workspace-folder . cargo build --release -p devcontainer-mcp

# Or using DevPod
devpod up . --id devcontainer-mcp --provider docker --open-ide=false
devpod ssh devcontainer-mcp --command "cd /workspaces/devcontainer-mcp && cargo build --workspace"

CI/CD

• プルリクエスト — cargo check、cargo test、cargo clippy、cargo fmt が自動的に実行されます
• リリース — GitHub リリースを作成すると、4 つのすべてのプラットフォーム向けのバイナリがビルドされます

ライセンス

MIT