用途：在 devcontainer 中统一配置 MCP 服务器，供 Kiro、Claude Code、Amazon Q/Codex 等代理使用，并处理新增、调试或迁移配置的场景。
主要能力：以 ~/.devcontainer-state/ai/mcp/servers.json 为唯一来源（已 gitignore，含凭据），仓库内保留 servers.json.template 模板。容器启动时由 post_create.sh 分发：Kiro CLI 复制到 ~/.kiro/settings/mcp.json；Claude Code 将 mcpServers 合并进 ~/.claude/settings.json；Amazon Q/Codex 复制到 ${WORKSPACE_ROOT}/.amazonq/mcp.json。VS Code/Copilot 例外，使用 .vscode/mcp.json，顶层键为 servers，env 用 ${ENV_VAR} 引用，需单独维护并提交仓库。
源文件格式为 mcpServers 下按服务器名配置 command、args、env。已知服务器环境变量：Trello 使用 TRELLO_API_KEY、TRELLO_TOKEN（不是 TRELLO_API_TOKEN）、可选 TRELLO_BOARD_ID；GitHub 使用 GITHUB_PERSONAL_ACCESS_TOKEN 或 GITHUB_TOKEN。变量名不匹配是最常见失败原因。
新增服务器流程：先在容器内手动测试，例如 echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | ENV_VAR=value timeout 5 npx -y <package-name> 2>/dev/null，期望返回含 result.serverInfo 的 JSON；再在主机编辑 servers.json 添加条目；然后重建容器或手动运行 post_create.sh；如用 Copilot，另在 .vscode/mcp.json 添加 servers 格式条目。
限制与注意：全局 npm 包通过 ~/.cache/npm-global 在重建后保留；凭据只留在 devcontainer-state，不进入项目仓库。常见问题包括包未安装、环境变量名错误、配置写错文件或格式、servers.json 不存在、代理会话未重启等，需按对应方式修复。资料未提供具体版本要求、支持平台范围与更多服务器清单。