devcontainer-mcp

devcontainer-mcp

让 AI Agent 拥有自己的开发环境，而不是使用你的环境。

devcontainer-mcp 是一个 MCP 服务，可让 AI 编码 Agent 使用 dev 容器，并在三种后端上创建、管理和工作：本地 Docker、DevPod 和 GitHub Codespaces。Agent 在隔离容器中构建、测试并交付代码，让你的笔记本电脑保持干净。

适用于 GitHub Copilot、Claude、Cursor、opencode 以及任何兼容 MCP 的客户端。

问题

AI Agent 编写代码时，需要在某个环境中运行代码。目前，这意味着使用你的主机：

• 🔴 污染主机 — Agent 安装软件包、修改 PATH，并留下构建产物
• 🔴 “在我的机器上能运行” — Agent 会假定你的本地工具链与生产环境一致
• 🔴 缺乏隔离 — 一个项目的依赖可能会破坏另一个项目
• 🔴 安全风险 — Agent 会以你的用户权限运行任意命令
• 🔴 硬件限制 — 你只能使用本地机器的资源

解决方案

devcontainer 规范已经定义了可复现的、基于容器的开发环境。每个大型项目都会提供 .devcontainer/devcontainer.json。但 AI Agent 一直无法使用它们——直到现在。

devcontainer-mcp 提供 45 个 MCP 工具，让任何 AI Agent 都能：

1. 启动任何仓库的 dev 容器——在本地、云虚拟机或 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）；如果缺少某个 CLI，MCP 服务会返回实用的错误信息和安装说明。

提供适用于 linux-x64、linux-arm64、darwin-x64 和 darwin-arm64 的二进制文件。

主机保护与退出选项

安装程序会配置两个 Agent 钩子（Claude Code 和 GitHub Copilot CLI），这些钩子仅在包含 .devcontainer/devcontainer.json 的目录中启用：

• devcontainer-guard (PreToolUse) — 阻止在主机上执行 Shell 命令，从而让 Agent 通过 MCP 工具运行构建、测试和程序。主机安全命令（git、gh）会列入允许列表，并且两个钩子都采用故障时放行策略——如果缺少 jq 或无法解析载荷，命令会被允许执行，而不是被拦截。
• devcontainer-skill-loader (SessionStart) — 将 SKILL.md 使用指南作为上下文注入。

在仓库中关闭

有时，项目会附带过时或无人维护的 .devcontainer，而你并不想通过它来处理工作。若要为该仓库禁用这两个钩子，请在仓库根目录创建一个标记文件：

touch .devcontainer-mcp-disable

存在 .devcontainer-mcp-disable 时，防护机制会允许主机命令通过，技能加载器也会跳过上下文注入——Agent 会在本地工作，就像没有声明 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]

三种后端，一个接口

后端	最适用于	需要	需要身份验证？
devcontainer CLI（devcontainer_*）	本地 Docker——快速、简单	@devcontainers/cli + Docker	否
DevPod（devpod_*）	多云：Docker、K8s、AWS、Azure、GCP	DevPod CLI	可选（云服务提供商）
Codespaces（codespaces_*）	GitHub 托管的云环境	gh CLI	是（auth 句柄）

身份验证代理

Agent 不会看到原始令牌。取而代之的是：

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	创建并启动本地开发容器
devcontainer_exec	在运行中的开发容器内执行命令
devcontainer_build	构建开发容器镜像
devcontainer_read_config	以 JSON 格式读取合并后的 devcontainer 配置
devcontainer_list_configs	在工作区中发现所有 devcontainer.json 文件（单容器和多容器）
devcontainer_stop	停止开发容器（通过 Docker API）
devcontainer_remove	移除开发容器及其资源
devcontainer_status	按工作区文件夹获取开发容器状态
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 失败时，完整的构建输出（包括错误）会返回给 Agent。Agent 可以读取错误、修复 Dockerfile 或 devcontainer.json，然后重试 — 使开发环境成为由 Agent 动态管理的资产，而非静态前置条件。

多容器工作区

devcontainer 规范支持在一个工作区中连接多个容器：为每个服务在 .devcontainer/<name>/devcontainer.json 中放置配置文件，并让每个配置指向共享的 docker-compose.yml。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_*）都接受可选的 config 参数，用于指定特定的 devcontainer.json。单容器工作流保持不变——config 默认为 devcontainer CLI 自动检测到的配置。
• 歧义处理 — 当工作区包含多个配置且未提供 config 时，查询类工具（status、exec、stop、remove、file_*）会返回结构化的 Ambiguous 结果，列出所有匹配的容器，供 Agent 选择。status 会以 {"state":"Ambiguous","candidates":[...],"hint":"..."} 的形式报告此情况。
• 可靠的容器匹配 — 通过 com.docker.compose.service + com.docker.compose.project.config_files 识别同级 compose 容器（而不使用不可靠的 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