Containerization Assist

Containerization Assist MCP 服务

一款 AI 驱动的容器化助手，可通过 VS Code 和其他兼容 MCP 的工具帮助你构建、扫描和部署 Docker 容器。

查看完整文档 →

安装

功能

核心功能

• 🐳 Docker 集成：构建、扫描和部署容器镜像
• ☸️ Kubernetes 支持：生成清单并部署应用
• 🤖 AI 驱动：智能生成和优化 Dockerfile
• 🧠 知识增强：借助安全和性能最佳实践，通过 AI 驱动改进内容
• 🔄 智能工具路由：自动解析依赖并执行
• 📊 进度跟踪：通过 MCP 通知实时更新进度
• 🔒 安全扫描：内置漏洞扫描，并提供 AI 驱动的建议
• ✨ 智能分析：结合上下文提供建议
• 策略驱动系统（v3.0）
  • 生成前配置
  • 知识筛选和加权
  • 模板注入
  • 语义验证
  • 跨工具一致性

策略系统（v3.0）

通过 Rego 策略全面控制容器化过程：

• 生成前配置：设置资源、基础镜像和构建策略的默认值
• 生成时引导：筛选知识库，自动注入模板
• 生成后验证：语义检查、安全评分和跨工具一致性

包含的策略示例：

• 基于环境的策略（dev/staging/prod）
• 按团队层级进行成本控制
• 安全优先的组织
• 多云注册表治理
• 速度优化型开发

详情请参阅策略编写指南。

系统要求

• Node.js 20+
• Docker 或 Docker Desktop
• 可选：Trivy（用于安全扫描功能）
• 可选：Kubernetes（用于部署功能）

手动安装

将以下内容添加到 VS Code 设置中，或在项目中创建 .vscode/mcp.json：

{
  "servers": {
    "ca": {
      "command": "npx",
      "args": ["-y", "containerization-assist-mcp", "start"],
      "env": {
         "LOG_LEVEL": "info"
      }
    }
  }
}

重启 VS Code，即可在 GitHub Copilot 中启用 MCP 服务。

SDK 用法（不使用 MCP）

直接使用工具而不通过 MCP 协议（例如，用于 VS Code 扩展或程序化访问）：

import { analyzeRepo, buildImageContext, scanImage } from 'containerization-assist-mcp/sdk';
import { execSync } from 'child_process';

// Simple function calls - no MCP server needed
const analysis = await analyzeRepo({ repositoryPath: './myapp' });
if (analysis.ok) {
  console.log('Detected:', analysis.value.modules);
}

// buildImageContext returns build context with security analysis and commands
const buildContext = await buildImageContext({ path: './myapp', imageName: 'myapp:v1', platform: 'linux/amd64' });
if (buildContext.ok) {
  const { securityAnalysis, nextAction } = buildContext.value;
  console.log('Security risk:', securityAnalysis.riskLevel);
  
  // Execute the generated build command from the build context directory
  execSync(nextAction.buildCommand.command, {
    cwd: buildContext.value.context.buildContextPath,
    env: { ...process.env, ...nextAction.buildCommand.environment }
  });
}

const scan = await scanImage({ imageId: 'myapp:v1' });

完整的 SDK 文档请参阅 SDK 集成示例。

Windows 用户

在 Windows 上，请使用 Windows Docker 管道：

"DOCKER_SOCKET": "//./pipe/docker_engine"

快速入门

了解容器化工作流最简单的方式是查看一个端到端示例：

单应用容器化流程

此 MCP 服务将引导你完成单个应用的完整容器化工作流。流程如下：

1. 分析代码库 → 了解应用所用的语言、框架和依赖项
2. 生成 Dockerfile → 创建经过优化并强化安全性的容器配置
3. 构建镜像 → 将应用编译为 Docker 镜像
4. 扫描镜像 → 识别安全漏洞并获取修复指导
5. 标记镜像 → 为镜像添加合适的版本标签
6. 生成 K8s 清单 → 创建 Kubernetes 部署配置
7. 准备集群 → 设置命名空间和先决条件，然后使用 kubectl apply 部署
8. 验证 → 确认部署健康且已就绪

先决条件

开始之前，请确保你已准备好：

• Docker：Docker 守护进程正在运行，且套接字可访问（应能运行 docker ps）
  • Linux/Mac：/var/run/docker.sock 可访问
  • Windows：Docker Desktop 已安装，且 //./pipe/docker_engine 可访问
• Kubernetes（可选，用于部署功能）：
  • 有效的 kubeconfig，位于 ~/.kube/config
  • 可连接集群（应能运行 kubectl cluster-info）
  • 具备部署、服务和命名空间所需的 RBAC 权限
• Node.js：版本 20 或更高
• MCP 客户端：VS Code with Copilot、Claude Desktop 或其他兼容 MCP 的客户端

自然语言工作流示例

在 MCP 客户端（VS Code Copilot、Claude Desktop 等）中完成配置后，使用自然语言：

开始流程：

"Analyze my Java application for containerization"

构建容器：

"Generate an optimized Dockerfile with security best practices"
"Build a Docker image tagged myapp:v1.0.0"
"Scan the image for vulnerabilities"

部署到 Kubernetes：

"Generate Kubernetes manifests for this application"
"Prepare my cluster and deploy to the default namespace"
"Verify the deployment is healthy"

单操作员模式

此服务针对每次由一名工程师容器化一个应用进行了优化。主要特点：

• 顺序执行：每个工具都会基于前序步骤的结果执行
• 快速失败验证：如果 Docker/Kubernetes 不可用，会提供清晰且可操作的错误信息
• 确定性的 AI 生成：工具通过内置提示词工程提供可复现的输出
• 实时进度：长时间运行的操作期间，MCP 通知会向客户端推送进度更新

多模块/单体仓库支持

此服务可检测并支持包含多个可独立部署服务的单体仓库结构：

• 自动检测：analyze-repo 可识别单体仓库模式（npm workspaces、services/、apps/ 目录）
• 自动生成多模块配置：generate-dockerfile 和 generate-k8s-manifests 支持多模块工作流
• 保守防护：不会将共享库和实用工具目录纳入容器化

多模块工作流示例：

1. "Analyze my monorepo at ./my-monorepo"
   → Detects 3 modules: api-gateway, user-service, notification-service

2. "Generate Dockerfiles"
   → Automatically creates Dockerfiles for all 3 modules:
     - services/api-gateway/Dockerfile
     - services/user-service/Dockerfile
     - services/notification-service/Dockerfile

3. "Generate K8s manifests"
   → Automatically creates manifests for all 3 modules

4. Optional: "Generate Dockerfile for user-service module"
   → Creates module-specific deployment manifests

检测标准：

• 工作区配置（npm、yarn、pnpm workspaces、lerna、nx、turborepo、cargo workspace）
• 每个服务有独立的 package.json、pom.xml、go.mod、Cargo.toml
• 独立的入口点和构建配置
• 排除：shared/、common/、lib/、packages/utils 目录

可用工具

此服务提供 11 个按功能分类的 MCP 工具：

分析与规划

工具	描述
analyze-repo	通过解析配置文件分析代码库结构并检测技术栈

Dockerfile 操作

工具	描述
generate-dockerfile	从知识库收集见解，并返回创建 Dockerfile 的要求
fix-dockerfile	分析 Dockerfile 中的问题（包括组织策略验证），并返回基于知识库的修复建议

镜像操作

工具	描述
build-image-context	准备 Docker 构建上下文，进行安全分析并返回构建命令
scan-image	扫描 Docker 镜像中的安全漏洞并提供修复指导（使用 Trivy CLI）
tag-image	为 Docker 镜像添加包含版本和注册表信息的标签
push-image	将 Docker 镜像推送到注册表

Kubernetes 操作

工具	描述
generate-k8s-manifests	收集见解，并返回创建 Kubernetes/Helm/ACA/Kustomize 清单的要求
prepare-cluster	准备 Kubernetes 集群以进行部署
verify-deploy	验证 Kubernetes 部署状态

实用工具

工具	描述
ops	用于 ping 和服务器状态检查的运维实用工具

工作流工具

交互式工作流工具会返回分步计划（在 VS Code Copilot Chat 中，输出默认处于折叠状态）：

工具	描述	输入
create-containerization-policy	编写自定义 OPA Rego 策略的分步指导	无
kind-loop	本地开发循环：分析 → 构建 → 扫描 → 部署到 Kind	namespace（可选）、imageName（可选）
aks-loop	远程开发循环：分析 → 构建 → 推送 → 部署到 AKS	registry、resourceGroup、clusterName（必需）；namespace、imageName（可选）

版本追踪

所有生成的构件都包含版本元数据，便于追踪它们由哪个版本的 containerization-assist 生成。

Dockerfile（generate-dockerfile）：

工具输出包含 attributionLabels.labels，其中带有版本标签；该标签会作为 LABEL 指令添加到生成的 Dockerfile 中：

标签	值	用途
com.azure.containerizationassist.version	包版本（例如，1.4.0）	使用的 containerization-assist 版本

Kubernetes 清单（generate-k8s-manifests）：

工具输出包含 attributionLabels.annotations，并应用于所有生成的 Kubernetes 资源元数据：

类型	键	值	用途
注解	com.azure.containerizationassist/version	包版本（例如，1.4.0）	使用的 containerization-assist 版本

组织可以通过策略系统的 orgStandards.requiredLabels 配置添加自定义标签。

支持的技术

语言和框架

• Java：Spring Boot、Quarkus、Micronaut（Java 8-21）
• .NET：ASP.NET Core、Blazor（.NET 6.0+）

构建系统

• Maven、Gradle（Java）
• dotnet CLI（.NET）

配置

环境变量

以下环境变量用于控制服务行为：

变量	描述	默认值	必需
DOCKER_SOCKET	Docker 套接字路径	/var/run/docker.sock（Linux/Mac） //./pipe/docker_engine（Windows）	否
DOCKER_HOST	Docker 主机 URI（unix://、tcp://、http://、https://、npipe://）	自动检测	否
DOCKER_TIMEOUT	Docker 操作超时时间（毫秒）	60000（60 秒）	否
KUBECONFIG	Kubernetes 配置文件路径	~/.kube/config	否
K8S_NAMESPACE	默认 Kubernetes 命名空间	default	否
LOG_LEVEL	日志级别	info	否
WORKSPACE_DIR	操作的工作目录	当前目录	否
MCP_MODE	启用 MCP 协议模式（日志输出到 stderr）	false	否
MCP_QUIET	在 MCP 模式下抑制非必要输出	false	否
CONTAINERIZATION_ASSIST_TOOL_LOGS_DIR_PATH	工具执行日志（JSON 格式）的目录路径	已禁用	否
CUSTOM_POLICY_PATH	自定义策略的目录路径（最高优先级）	未设置	否

进度通知： 长时间运行的操作（build、deploy、scan-image）会通过 MCP 通知实时发送进度更新。MCP 客户端可以订阅这些通知，向用户显示进度。

工具执行日志

启用将所有工具执行的详细日志记录到 JSON 文件，以便调试和审计：

export CONTAINERIZATION_ASSIST_TOOL_LOGS_DIR_PATH=/path/to/logs

日志文件格式：

• 文件名：ca-tool-logs-${timestamp}.jsonl
• 示例：ca-tool-logs-2025-10-13T14-30-15-123Z.jsonl

日志内容：

{
  "timestamp": "2025-10-13T14:30:15.123Z",
  "toolName": "analyze-repo",
  "input": { "path": "/workspace/myapp" },
  "output": { "language": "typescript", "framework": "express" },
  "success": true,
  "durationMs": 245,
  "error": "Error message if failed",
  "errorGuidance": {
    "hint": "Suggested fix",
    "resolution": "Step-by-step instructions"
  }
}

启动时会验证日志目录，确保该目录可写。

策略系统

策略系统使用 OPA Rego 来实施安全、质量和合规性要求。Rego 是 Open Policy Agent 提供的行业标准策略语言，支持表达力丰富的规则和强大的内置函数。

默认行为（无需配置）： 默认情况下，policies/ 目录中的所有策略都会自动发现并合并：

• policies/security-baseline.rego - 基本安全规则（禁止使用 root 用户、检测密钥、禁止特权容器）
• policies/base-images.rego - 基础映像治理（推荐使用 Microsoft Azure Linux、禁止使用 :latest 标签、弃用版本）
• policies/container-best-practices.rego - Docker 最佳实践（HEALTHCHECK、多阶段构建、层优化）

这开箱即用地提供全面的安全和质量要求。

自定义策略

策略系统支持四个按优先级排序的搜索路径，便于自定义：

优先级顺序（从高到低）：

1. 通过 CUSTOM_POLICY_PATH 环境变量指定的自定义目录（最高优先级）
2. <git-root>/.containerization-assist/policy/ 下的项目目录（由 git 跟踪）
3. ~/.config/containerization-assist/policy/ 下的全局目录（符合 XDG 标准）
4. 内置 policies/（随软件包提供，优先级最低）

迁移说明：policies.user/ 目录已弃用。对于项目专属策略，请在 git 根目录下使用 .containerization-assist/policy/。对于适用于所有用户的策略，请使用 ~/.config/containerization-assist/policy/。旧目录仍可使用，但会输出弃用警告。

快速开始

# Option 1: Global policies (no env var needed)
mkdir -p ~/.config/containerization-assist/policy

# Copy example policy from the npm package
cp node_modules/containerization-assist-mcp/policies.user.examples/allow-all-registries.rego \
   ~/.config/containerization-assist/policy/

# Policies are auto-reloaded on the next tool execution — no restart needed

或者在 .vscode/mcp.json 中设置自定义位置：

{
  "servers": {
    "ca": {
      "env": {
        "CUSTOM_POLICY_PATH": "/path/to/policies"
      }
    }
  }
}

预构建示例策略

policies.user.examples/ 目录（包含在 npm 包中）提供了三个可直接使用的示例：

示例	用途	使用场景
allow-all-registries.rego	覆盖 MCR 首选项	Docker Hub、GCR、ECR、私有注册表
warn-only-mode.rego	仅提供建议的强制执行模式	测试、逐步采用、开发环境
custom-organization-template.rego	组织模板	自定义标签、注册表、合规性

详细用法请参阅 policies.user.examples/README.md。

内置策略

默认包含三个适用于生产环境的 Rego 策略：

• policies/security-baseline.rego - 基本安全规则（防止使用 root 用户、检测机密信息、限制特权容器）
• policies/base-images.rego - 基础镜像治理（推荐使用 Microsoft Azure Linux、禁止使用 :latest 标签、弃用版本）
• policies/container-best-practices.rego - Docker 最佳实践（HEALTHCHECK、多阶段构建、层优化）

用户策略会按包命名空间覆盖内置策略。

策略文件格式（Rego）：

package containerization.custom_policy

# Blocking violations
violations contains result if {
  input_type == "dockerfile"
  regex.match(`FROM\s+[^:]+:latest`, input.content)

  result := {
    "rule": "block-latest-tag",
    "category": "quality",
    "priority": 80,
    "severity": "block",
    "message": "Using :latest tag is not allowed. Specify explicit version tags.",
    "description": "Prevent :latest for reproducibility",
  }
}

# Non-blocking warnings
warnings contains result if {
  input_type == "dockerfile"
  not regex.match(`HEALTHCHECK`, input.content)

  result := {
    "rule": "suggest-healthcheck",
    "category": "quality",
    "priority": 70,
    "severity": "warn",
    "message": "Consider adding HEALTHCHECK instruction for container monitoring",
    "description": "HEALTHCHECK improves container lifecycle management",
  }
}

# Policy decision
default allow := false
allow if count(violations) == 0

# Result structure
result := {
  "allow": allow,
  "violations": violations,
  "warnings": warnings,
  "suggestions": [],
  "summary": {
    "total_violations": count(violations),
    "total_warnings": count(warnings),
    "total_suggestions": 0,
  },
}

优先级：

• 90-100：安全规则（最高优先级）
• 70-89：质量规则
• 50-69：性能规则
• 30-49：合规规则

使用策略：

# List discovered policies
npx containerization-assist-mcp list-policies

# List policies and show merged result
npx containerization-assist-mcp list-policies --show-merged

# Validate Dockerfile with policies (automatic discovery)
npx containerization-assist-mcp fix-dockerfile --path ./Dockerfile

创建自定义策略：

请参阅策略自定义指南以及 policies/ 中的现有策略，了解示例。

测试策略：

# Validate policy syntax
opa check .containerization-assist/policy/my-policy.rego

# Run policy tests
opa test .containerization-assist/policy/

# Test with MCP Inspector
npx @modelcontextprotocol/inspector containerization-assist-mcp start

MCP Inspector（测试）

npx @modelcontextprotocol/inspector containerization-assist-mcp start

故障排除

Docker 连接问题

# Check Docker is running
docker ps

# Check socket permissions (Linux/Mac)
ls -la /var/run/docker.sock

# For Windows, ensure Docker Desktop is running

MCP 连接问题

# Test with MCP Inspector
npx @modelcontextprotocol/inspector containerization-assist-mcp start

# Check logs with debug level
npx -y containerization-assist-mcp start --log-level debug

Kubernetes 连接问题

使用 Kubernetes 工具时，服务会执行快速失败验证。如果遇到 Kubernetes 错误：

未找到 Kubeconfig

# Check if kubeconfig exists
ls -la ~/.kube/config

# Verify kubectl can connect
kubectl cluster-info

# If using cloud providers, update kubeconfig:
# AWS EKS
aws eks update-kubeconfig --name <cluster-name> --region <region>

# Google GKE
gcloud container clusters get-credentials <cluster-name> --zone <zone>

# Azure AKS
az aks get-credentials --resource-group <rg> --name <cluster-name>

连接超时或被拒绝

# Verify cluster is running
kubectl get nodes

# Check API server address
kubectl config view

# Test connectivity to API server
kubectl cluster-info dump

# Verify firewall rules allow connection to API server port (typically 6443)

身份验证或授权错误

# Check current context and user
kubectl config current-context
kubectl config view --minify

# Test permissions
kubectl auth can-i create deployments --namespace default
kubectl auth can-i create services --namespace default

# If using cloud providers, refresh credentials:
# AWS EKS: re-run update-kubeconfig
# GKE: run gcloud auth login
# AKS: run az login

上下文无效或缺失

# List available contexts
kubectl config get-contexts

# Set a context
kubectl config use-context <context-name>

# View current configuration
kubectl config view

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

有关如何获取此项目帮助的信息，请参阅 SUPPORT.md。

商标

此项目可能包含项目、产品或服务的商标或徽标。经授权使用 Microsoft 商标或徽标时，必须遵守Microsoft 商标与品牌指南。在此项目的修改版本中使用 Microsoft 商标或徽标，不得造成混淆，也不得暗示 Microsoft 为其提供赞助。使用任何第三方商标或徽标时，均须遵守相应第三方的政策。