Containerization Assist MCP Server

An AI-powered containerization assistant that helps you build, scan, and deploy Docker containers through VS Code and other MCP-compatible tools.

Full documentation →

Install

Features

Core Capabilities

• 🐳 Docker Integration: Build, scan, and deploy container images
• ☸️ Kubernetes Support: Generate manifests and deploy applications
• 🤖 AI-Powered: Intelligent Dockerfile generation and optimization
• 🧠 Knowledge Enhanced: AI-driven content improvement with security and performance best practices
• 🔄 Intelligent Tool Routing: Automatic dependency resolution and execution
• 📊 Progress Tracking: Real-time progress updates via MCP notifications
• 🔒 Security Scanning: Built-in vulnerability scanning with AI-powered suggestions
• ✨ Smart Analysis: Context-aware recommendations
• Policy-Driven System (v3.0)
  • Pre-generation configuration
  • Knowledge filtering and weighting
  • Template injection
  • Semantic validation
  • Cross-tool consistency

Policy System (v3.0)

Full control over containerization through Rego policies:

• Configure Before Generation: Set defaults for resources, base images, build strategy
• Guide During Generation: Filter knowledge base, inject templates automatically
• Validate After Generation: Semantic checks, security scoring, cross-tool consistency

Example Policies Included:

• Environment-based strategy (dev/staging/prod)
• Cost control by team tier
• Security-first organization
• Multi-cloud registry governance
• Speed-optimized development

See Policy Authoring Guide for details.

System Requirements

• Node.js 20+
• Docker or Docker Desktop
• Optional: Trivy (for security scanning features)
• Optional: Kubernetes (for deployment features)

Manual Install

Add the following to your VS Code settings or create .vscode/mcp.json in your project:

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

Restart VS Code to enable the MCP server in GitHub Copilot.

SDK Usage (Without MCP)

For direct tool usage without MCP protocol (e.g., VS Code extensions, programmatic access):

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' });

See the SDK integration examples for full SDK documentation.

Windows Users

For Windows, use the Windows Docker pipe:

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

Quick Start

The easiest way to understand the containerization workflow is through an end-to-end example:

Single-App Containerization Journey

This MCP server guides you through a complete containerization workflow for a single application. The journey follows this sequence:

1. Analyze Repository → Understand your application's language, framework, and dependencies
2. Generate Dockerfile → Create an optimized, security-hardened container configuration
3. Build Image → Compile your application into a Docker image
4. Scan Image → Identify security vulnerabilities and get remediation guidance
5. Tag Image → Apply appropriate version tags to your image
6. Generate K8s Manifests → Create deployment configurations for Kubernetes
7. Prepare Cluster → Set up namespace and prerequisites, then deploy with kubectl apply
8. Verify → Confirm deployment health and readiness

Prerequisites

Before starting, ensure you have:

• Docker: Running Docker daemon with accessible socket (docker ps should work)
  • Linux/Mac: /var/run/docker.sock accessible
  • Windows: Docker Desktop with //./pipe/docker_engine accessible
• Kubernetes (optional, for deployment features):
  • Valid kubeconfig at ~/.kube/config
  • Cluster connectivity (kubectl cluster-info should work)
  • Appropriate RBAC permissions for deployments, services, namespaces
• Node.js: Version 20 or higher
• MCP Client: VS Code with Copilot, Claude Desktop, or another MCP-compatible client

Example Workflow with Natural Language

Once configured in your MCP client (VS Code Copilot, Claude Desktop, etc.), use natural language:

Starting the Journey:

"Analyze my Java application for containerization"

Building the Container:

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

Deploying to Kubernetes:

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

Single-Operator Model

This server is optimized for one engineer containerizing one application at a time. Key characteristics:

• Sequential execution: Each tool builds on the results of previous steps
• Fast-fail validation: Clear, actionable error messages if Docker/Kubernetes are unavailable
• Deterministic AI generation: Tools provide reproducible outputs through built-in prompt engineering
• Real-time progress: MCP notifications surface progress updates to clients during long-running operations

Multi-Module/Monorepo Support

The server detects and supports monorepo structures with multiple independently deployable services:

• Automatic Detection: analyze-repo identifies monorepo patterns (npm workspaces, services/, apps/ directories)
• Automated Multi-Module Generation: generate-dockerfile and generate-k8s-manifests support multi-module workflows
• Conservative Safeguards: Excludes shared libraries and utility folders from containerization

Multi-Module Workflow Example:

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

Detection Criteria:

• Workspace configurations (npm, yarn, pnpm workspaces, lerna, nx, turborepo, cargo workspace)
• Separate package.json, pom.xml, go.mod, Cargo.toml per service
• Independent entry points and build configs
• EXCLUDES: shared/, common/, lib/, packages/utils directories

Available Tools

The server provides 11 MCP tools organized by functionality:

Analysis & Planning

Tool	Description
analyze-repo	Analyze repository structure and detect technologies by parsing config files

Dockerfile Operations

Tool	Description
generate-dockerfile	Gather insights from knowledge base and return requirements for Dockerfile creation
fix-dockerfile	Analyze Dockerfile for issues including organizational policy validation and return knowledge-based fix recommendations

Image Operations

Tool	Description
build-image-context	Prepare Docker build context with security analysis and return build commands
scan-image	Scan Docker images for security vulnerabilities with remediation guidance (uses Trivy CLI)
tag-image	Tag Docker images with version and registry information
push-image	Push Docker images to a registry

Kubernetes Operations

Tool	Description
generate-k8s-manifests	Gather insights and return requirements for Kubernetes/Helm/ACA/Kustomize manifest creation
prepare-cluster	Prepare Kubernetes cluster for deployment
verify-deploy	Verify Kubernetes deployment status

Utilities

Tool	Description
ops	Operational utilities for ping and server status

Workflow Tools

Interactive workflow tools that return step-by-step plans (output is collapsed by default in VS Code Copilot Chat):

Tool	Description	Inputs
create-containerization-policy	Step-by-step guidance for authoring a custom OPA Rego policy	None
kind-loop	Local dev loop: analyze → build → scan → deploy to Kind	namespace (optional), imageName (optional)
aks-loop	Remote dev loop: analyze → build → push → deploy to AKS	registry, resourceGroup, clusterName (required); namespace, imageName (optional)

Version Tracking

All generated artifacts include version metadata so you can track which version of containerization-assist produced them.

Dockerfiles (generate-dockerfile):

The tool output includes attributionLabels.labels with a version label, included as a LABEL instruction in the generated Dockerfile:

Label	Value	Purpose
com.azure.containerizationassist.version	Package version (e.g., 1.4.0)	Version of containerization-assist used

Kubernetes Manifests (generate-k8s-manifests):

The tool output includes attributionLabels.annotations applied to all generated Kubernetes resource metadata:

Type	Key	Value	Purpose
Annotation	com.azure.containerizationassist/version	Package version (e.g., 1.4.0)	Version of containerization-assist used

Organizations can add custom labels via the policy system's orgStandards.requiredLabels configuration.

Supported Technologies

Languages & Frameworks

• Java: Spring Boot, Quarkus, Micronaut (Java 8-21)
• .NET: ASP.NET Core, Blazor (.NET 6.0+)

Build Systems

• Maven, Gradle (Java)
• dotnet CLI (.NET)

Configuration

Environment Variables

The following environment variables control server behavior:

Variable	Description	Default	Required
DOCKER_SOCKET	Docker socket path	/var/run/docker.sock (Linux/Mac) //./pipe/docker_engine (Windows)	No
DOCKER_HOST	Docker host URI (unix://, tcp://, http://, https://, npipe://)	Auto-detected	No
DOCKER_TIMEOUT	Docker operation timeout in milliseconds	60000 (60s)	No
KUBECONFIG	Path to Kubernetes config file	~/.kube/config	No
K8S_NAMESPACE	Default Kubernetes namespace	default	No
LOG_LEVEL	Logging level	info	No
WORKSPACE_DIR	Working directory for operations	Current directory	No
MCP_MODE	Enable MCP protocol mode (logs to stderr)	false	No
MCP_QUIET	Suppress non-essential output in MCP mode	false	No
CONTAINERIZATION_ASSIST_TOOL_LOGS_DIR_PATH	Directory path for tool execution logs (JSON format)	Disabled	No
CUSTOM_POLICY_PATH	Directory path for custom policies (highest priority)	Not set	No

Progress Notifications: Long-running operations (build, deploy, scan-image) emit real-time progress updates via MCP notifications. MCP clients can subscribe to these notifications to display progress to users.

Tool Execution Logging

Enable detailed logging of all tool executions to JSON files for debugging and auditing:

export CONTAINERIZATION_ASSIST_TOOL_LOGS_DIR_PATH=/path/to/logs

Log File Format:

• Filename: ca-tool-logs-${timestamp}.jsonl
• Example: ca-tool-logs-2025-10-13T14-30-15-123Z.jsonl

Log Contents:

{
  "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"
  }
}

The logging directory is validated at startup to ensure it's writable.

Policy System

The policy system uses OPA Rego for security, quality, and compliance enforcement. Rego is the industry-standard policy language from Open Policy Agent, providing expressive rules with rich built-in functions.

Default Behavior (No Configuration Needed): By default, all policies in the policies/ directory are automatically discovered and merged:

• policies/security-baseline.rego - Essential security rules (root user prevention, secrets detection, privileged containers)
• policies/base-images.rego - Base image governance (Microsoft Azure Linux recommendation, no :latest tag, deprecated versions)
• policies/container-best-practices.rego - Docker best practices (HEALTHCHECK, multi-stage builds, layer optimization)

This provides comprehensive out-of-the-box security and quality enforcement.

Policy Customization

The policy system supports four priority-ordered search paths for easy customization:

Priority Order (highest to lowest):

1. Custom directory via CUSTOM_POLICY_PATH environment variable (highest priority)
2. Project directory at <git-root>/.containerization-assist/policy/ (tracked in git)
3. Global directory at ~/.config/containerization-assist/policy/ (XDG-compliant)
4. Built-in policies/ (shipped with package, lowest priority)

Migration Note: The policies.user/ directory is deprecated. For project-specific policies, use .containerization-assist/policy/ at your git root. For user-wide policies, use ~/.config/containerization-assist/policy/. The old directory still works but will log a deprecation warning.

Quick Start

# 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

Or set a custom location in .vscode/mcp.json:

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

Pre-Built Example Policies

The policies.user.examples/ directory (included in the npm package) provides three ready-to-use examples:

Example	Purpose	Use Case
allow-all-registries.rego	Override MCR preference	Docker Hub, GCR, ECR, private registries
warn-only-mode.rego	Advisory-only enforcement	Testing, gradual adoption, dev environments
custom-organization-template.rego	Organization template	Custom labels, registries, compliance

See policies.user.examples/README.md for detailed usage.

Built-In Policies

Three production-ready Rego policies are included by default:

• policies/security-baseline.rego - Essential security rules (root user prevention, secrets detection, privileged containers)
• policies/base-images.rego - Base image governance (Microsoft Azure Linux recommendation, no :latest tag, deprecated versions)
• policies/container-best-practices.rego - Docker best practices (HEALTHCHECK, multi-stage builds, layer optimization)

User policies override built-in policies by package namespace.

Policy File Format (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,
  },
}

Priority Levels:

• 90-100: Security rules (highest priority)
• 70-89: Quality rules
• 50-69: Performance rules
• 30-49: Compliance rules

Using Policies:

# 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

Creating Custom Policies:

See Policy Customization Guide and existing policies in policies/ for examples.

Testing 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 (Testing)

npx @modelcontextprotocol/inspector containerization-assist-mcp start

Troubleshooting

Docker Connection Issues

# 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 Connection Issues

# 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 Connection Issues

The server performs fast-fail validation when Kubernetes tools are used. If you encounter Kubernetes errors:

Kubeconfig Not Found

# 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>

Connection Timeout or Refused

# 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)

Authentication or Authorization Errors

# 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

Invalid or Missing Context

# List available contexts
kubectl config get-contexts

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

# View current configuration
kubectl config view

License

MIT License - See LICENSE file for details.

Support

See SUPPORT.md for information on how to get help with this project.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.