# Containerization Assist

> TypeScript MCP server for AI-powered containerization workflows with Docker and Kubernetes support

- **Type:** MCP server
- **Install:** `agentstack add mcp-azure-containerization-assist`
- **Verified:** Pending review
- **Seller:** [Azure](https://agentstack.voostack.com/s/azure)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 1.3.1
- **License:** MIT
- **Upstream author:** [Azure](https://github.com/Azure)
- **Source:** https://github.com/Azure/containerization-assist

## Install

```sh
agentstack add mcp-azure-containerization-assist
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Containerization Assist MCP Server

[](https://github.com/Azure/containerization-assist/actions/workflows/test-pipeline.yml)
[](https://github.com/Azure/containerization-assist/releases)
[](https://github.com/modelcontextprotocol/typescript-sdk)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
[](LICENSE)
[](https://azure.github.io/containerization-assist/)

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

> **[Full documentation →](https://azure.github.io/containerization-assist/)**

## Install

[](https://azure.github.io/containerization-assist/vscode-mcp-install-redirect.html)
[](https://azure.github.io/containerization-assist/vscode-insiders-mcp-install-redirect.html)

## 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](docs/guides/policy-authoring.md) for details.

## System Requirements

- Node.js 20+
- Docker or Docker Desktop
- Optional: [Trivy](https://aquasecurity.github.io/trivy/latest/getting-started/installation/) (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:

```json
{
  "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):

```typescript
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](docs/examples/README.md) for full SDK documentation.

### Windows Users

For Windows, use the Windows Docker pipe:
```json
"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:

```bash
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:**
```json
{
  "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 `/.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

```bash
# 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`:

```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 | Doc

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Azure](https://github.com/Azure)
- **Source:** [Azure/containerization-assist](https://github.com/Azure/containerization-assist)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **1.3.1** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-azure-containerization-assist
- Seller: https://agentstack.voostack.com/s/azure
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.