{
"markdown": "# Containerization Assist MCP Server\n\n[](https://github.com/Azure/containerization-assist/actions/workflows/test-pipeline.yml)\n[](https://github.com/Azure/containerization-assist/releases)\n[](https://github.com/modelcontextprotocol/typescript-sdk)\n[](https://nodejs.org)\n[](https://www.typescriptlang.org/)\n[](LICENSE)\n[](https://azure.github.io/containerization-assist/)\n\nAn AI-powered containerization assistant that helps you build, scan, and deploy Docker containers through VS Code and other MCP-compatible tools.\n\n> **[Full documentation β](https://azure.github.io/containerization-assist/)**\n\n## Install\n\n\n[](https://azure.github.io/containerization-assist/vscode-mcp-install-redirect.html)\n[](https://azure.github.io/containerization-assist/vscode-insiders-mcp-install-redirect.html)\n\n## Features\n\n### Core Capabilities\n\n- π³ **Docker Integration**: Build, scan, and deploy container images\n- βΈοΈ **Kubernetes Support**: Generate manifests and deploy applications\n- π€ **AI-Powered**: Intelligent Dockerfile generation and optimization\n- π§ **Knowledge Enhanced**: AI-driven content improvement with security and performance best practices\n- π **Intelligent Tool Routing**: Automatic dependency resolution and execution\n- π **Progress Tracking**: Real-time progress updates via MCP notifications\n- π **Security Scanning**: Built-in vulnerability scanning with AI-powered suggestions\n- β¨ **Smart Analysis**: Context-aware recommendations\n- **Policy-Driven System (v3.0)**\n - Pre-generation configuration\n - Knowledge filtering and weighting\n - Template injection\n - Semantic validation\n - Cross-tool consistency\n\n### Policy System (v3.0)\n\nFull control over containerization through Rego policies:\n\n- **Configure Before Generation**: Set defaults for resources, base images, build strategy\n- **Guide During Generation**: Filter knowledge base, inject templates automatically\n- **Validate After Generation**: Semantic checks, security scoring, cross-tool consistency\n\n**Example Policies Included**:\n- Environment-based strategy (dev/staging/prod)\n- Cost control by team tier\n- Security-first organization\n- Multi-cloud registry governance\n- Speed-optimized development\n\nSee [Policy Authoring Guide](docs/guides/policy-authoring.md) for details.\n\n## System Requirements\n\n- Node.js 20+\n- Docker or Docker Desktop\n- Optional: [Trivy](https://aquasecurity.github.io/trivy/latest/getting-started/installation/) (for security scanning features)\n- Optional: Kubernetes (for deployment features)\n\n## Manual Install\n\nAdd the following to your VS Code settings or create `.vscode/mcp.json` in your project:\n\n```json\n{\n \"servers\": {\n \"ca\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"containerization-assist-mcp\", \"start\"],\n \"env\": {\n \"LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nRestart VS Code to enable the MCP server in GitHub Copilot.\n\n### SDK Usage (Without MCP)\n\nFor direct tool usage without MCP protocol (e.g., VS Code extensions, programmatic access):\n\n```typescript\nimport { analyzeRepo, buildImageContext, scanImage } from 'containerization-assist-mcp/sdk';\nimport { execSync } from 'child_process';\n\n// Simple function calls - no MCP server needed\nconst analysis = await analyzeRepo({ repositoryPath: './myapp' });\nif (analysis.ok) {\n console.log('Detected:', analysis.value.modules);\n}\n\n// buildImageContext returns build context with security analysis and commands\nconst buildContext = await buildImageContext({ path: './myapp', imageName: 'myapp:v1', platform: 'linux/amd64' });\nif (buildContext.ok) {\n const { securityAnalysis, nextAction } = buildContext.value;\n console.log('Security risk:', securityAnalysis.riskLevel);\n \n // Execute the generated build command from the build context directory\n execSync(nextAction.buildCommand.command, {\n cwd: buildContext.value.context.buildContextPath,\n env: { ...process.env, ...nextAction.buildCommand.environment }\n });\n}\n\nconst scan = await scanImage({ imageId: 'myapp:v1' });\n```\n\nSee the [SDK integration examples](docs/examples/README.md) for full SDK documentation.\n\n### Windows Users\n\nFor Windows, use the Windows Docker pipe:\n```json\n\"DOCKER_SOCKET\": \"//./pipe/docker_engine\"\n```\n\n## Quick Start\n\nThe easiest way to understand the containerization workflow is through an end-to-end example:\n\n### Single-App Containerization Journey\n\nThis MCP server guides you through a complete containerization workflow for a single application. The journey follows this sequence:\n\n1. **Analyze Repository** β Understand your application's language, framework, and dependencies\n2. **Generate Dockerfile** β Create an optimized, security-hardened container configuration\n3. **Build Image** β Compile your application into a Docker image\n4. **Scan Image** β Identify security vulnerabilities and get remediation guidance\n5. **Tag Image** β Apply appropriate version tags to your image\n6. **Generate K8s Manifests** β Create deployment configurations for Kubernetes\n7. **Prepare Cluster** β Set up namespace and prerequisites, then deploy with `kubectl apply`\n8. **Verify** β Confirm deployment health and readiness\n\n### Prerequisites\n\nBefore starting, ensure you have:\n\n- **Docker**: Running Docker daemon with accessible socket (`docker ps` should work)\n - Linux/Mac: `/var/run/docker.sock` accessible\n - Windows: Docker Desktop with `//./pipe/docker_engine` accessible\n- **Kubernetes** (optional, for deployment features):\n - Valid kubeconfig at `~/.kube/config`\n - Cluster connectivity (`kubectl cluster-info` should work)\n - Appropriate RBAC permissions for deployments, services, namespaces\n- **Node.js**: Version 20 or higher\n- **MCP Client**: VS Code with Copilot, Claude Desktop, or another MCP-compatible client\n\n### Example Workflow with Natural Language\n\nOnce configured in your MCP client (VS Code Copilot, Claude Desktop, etc.), use natural language:\n\n**Starting the Journey:**\n```\n\"Analyze my Java application for containerization\"\n```\n\n**Building the Container:**\n```\n\"Generate an optimized Dockerfile with security best practices\"\n\"Build a Docker image tagged myapp:v1.0.0\"\n\"Scan the image for vulnerabilities\"\n```\n\n**Deploying to Kubernetes:**\n```\n\"Generate Kubernetes manifests for this application\"\n\"Prepare my cluster and deploy to the default namespace\"\n\"Verify the deployment is healthy\"\n```\n\n### Single-Operator Model\n\nThis server is optimized for **one engineer containerizing one application at a time**. Key characteristics:\n\n- **Sequential execution**: Each tool builds on the results of previous steps\n- **Fast-fail validation**: Clear, actionable error messages if Docker/Kubernetes are unavailable\n- **Deterministic AI generation**: Tools provide reproducible outputs through built-in prompt engineering\n- **Real-time progress**: MCP notifications surface progress updates to clients during long-running operations\n\n### Multi-Module/Monorepo Support\n\nThe server detects and supports monorepo structures with multiple independently deployable services:\n\n- **Automatic Detection**: `analyze-repo` identifies monorepo patterns (npm workspaces, services/, apps/ directories)\n- **Automated Multi-Module Generation**: `generate-dockerfile` and `generate-k8s-manifests` support multi-module workflows\n- **Conservative Safeguards**: Excludes shared libraries and utility folders from containerization\n\n**Multi-Module Workflow Example:**\n```\n1. \"Analyze my monorepo at ./my-monorepo\"\n β Detects 3 modules: api-gateway, user-service, notification-service\n\n2. \"Generate Dockerfiles\"\n β Automatically creates Dockerfiles for all 3 modules:\n - services/api-gateway/Dockerfile\n - services/user-service/Dockerfile\n - services/notification-service/Dockerfile\n\n3. \"Generate K8s manifests\"\n β Automatically creates manifests for all 3 modules\n\n4. Optional: \"Generate Dockerfile for user-service module\"\n β Creates module-specific deployment manifests\n```\n\n**Detection Criteria:**\n- Workspace configurations (npm, yarn, pnpm workspaces, lerna, nx, turborepo, cargo workspace)\n- Separate package.json, pom.xml, go.mod, Cargo.toml per service\n- Independent entry points and build configs\n- EXCLUDES: shared/, common/, lib/, packages/utils directories\n\n## Available Tools\n\nThe server provides 11 MCP tools organized by functionality:\n\n### Analysis & Planning\n| Tool | Description |\n|------|-------------|\n| `analyze-repo` | Analyze repository structure and detect technologies by parsing config files |\n\n### Dockerfile Operations\n| Tool | Description |\n|------|-------------|\n| `generate-dockerfile` | Gather insights from knowledge base and return requirements for Dockerfile creation |\n| `fix-dockerfile` | Analyze Dockerfile for issues including organizational policy validation and return knowledge-based fix recommendations |\n\n### Image Operations\n| Tool | Description |\n|------|-------------|\n| `build-image-context` | Prepare Docker build context with security analysis and return build commands |\n| `scan-image` | Scan Docker images for security vulnerabilities with remediation guidance (uses Trivy CLI) |\n| `tag-image` | Tag Docker images with version and registry information |\n| `push-image` | Push Docker images to a registry |\n\n### Kubernetes Operations\n| Tool | Description |\n|------|-------------|\n| `generate-k8s-manifests` | Gather insights and return requirements for Kubernetes/Helm/ACA/Kustomize manifest creation |\n| `prepare-cluster` | Prepare Kubernetes cluster for deployment |\n| `verify-deploy` | Verify Kubernetes deployment status |\n\n### Utilities\n| Tool | Description |\n|------|-------------|\n| `ops` | Operational utilities for ping and server status |\n\n### Workflow Tools\n\nInteractive workflow tools that return step-by-step plans (output is collapsed by default in VS Code Copilot Chat):\n\n| Tool | Description | Inputs |\n|------|-------------|--------|\n| `create-containerization-policy` | Step-by-step guidance for authoring a custom OPA Rego policy | None |\n| `kind-loop` | Local dev loop: analyze β build β scan β deploy to Kind | `namespace` (optional), `imageName` (optional) |\n| `aks-loop` | Remote dev loop: analyze β build β push β deploy to AKS | `registry`, `resourceGroup`, `clusterName` (required); `namespace`, `imageName` (optional) |\n\n### Version Tracking\n\nAll generated artifacts include version metadata so you can track which version of containerization-assist produced them.\n\n**Dockerfiles** (`generate-dockerfile`):\n\nThe tool output includes `attributionLabels.labels` with a version label, included as a `LABEL` instruction in the generated Dockerfile:\n\n| Label | Value | Purpose |\n|-------|-------|---------|\n| `com.azure.containerizationassist.version` | Package version (e.g., `1.4.0`) | Version of containerization-assist used |\n\n**Kubernetes Manifests** (`generate-k8s-manifests`):\n\nThe tool output includes `attributionLabels.annotations` applied to all generated Kubernetes resource metadata:\n\n| Type | Key | Value | Purpose |\n|------|-----|-------|---------|\n| Annotation | `com.azure.containerizationassist/version` | Package version (e.g., `1.4.0`) | Version of containerization-assist used |\n\nOrganizations can add custom labels via the policy system's `orgStandards.requiredLabels` configuration.\n\n## Supported Technologies\n\n### Languages & Frameworks\n- **Java**: Spring Boot, Quarkus, Micronaut (Java 8-21)\n- **.NET**: ASP.NET Core, Blazor (.NET 6.0+)\n\n### Build Systems\n- Maven, Gradle (Java)\n- dotnet CLI (.NET)\n\n## Configuration\n\n### Environment Variables\n\nThe following environment variables control server behavior:\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `DOCKER_SOCKET` | Docker socket path | `/var/run/docker.sock` (Linux/Mac)
`//./pipe/docker_engine` (Windows) | No |\n| `DOCKER_HOST` | Docker host URI (`unix://`, `tcp://`, `http://`, `https://`, `npipe://`) | Auto-detected | No |\n| `DOCKER_TIMEOUT` | Docker operation timeout in milliseconds | `60000` (60s) | No |\n| `KUBECONFIG` | Path to Kubernetes config file | `~/.kube/config` | No |\n| `K8S_NAMESPACE` | Default Kubernetes namespace | `default` | No |\n| `LOG_LEVEL` | Logging level | `info` | No |\n| `WORKSPACE_DIR` | Working directory for operations | Current directory | No |\n| `MCP_MODE` | Enable MCP protocol mode (logs to stderr) | `false` | No |\n| `MCP_QUIET` | Suppress non-essential output in MCP mode | `false` | No |\n| `CONTAINERIZATION_ASSIST_TOOL_LOGS_DIR_PATH` | Directory path for tool execution logs (JSON format) | Disabled | No |\n| `CUSTOM_POLICY_PATH` | Directory path for custom policies (highest priority) | Not set | No |\n\n**Progress Notifications:**\nLong-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.\n\n### Tool Execution Logging\n\nEnable detailed logging of all tool executions to JSON files for debugging and auditing:\n\n```bash\nexport CONTAINERIZATION_ASSIST_TOOL_LOGS_DIR_PATH=/path/to/logs\n```\n\n**Log File Format:**\n- Filename: `ca-tool-logs-${timestamp}.jsonl`\n- Example: `ca-tool-logs-2025-10-13T14-30-15-123Z.jsonl`\n\n**Log Contents:**\n```json\n{\n \"timestamp\": \"2025-10-13T14:30:15.123Z\",\n \"toolName\": \"analyze-repo\",\n \"input\": { \"path\": \"/workspace/myapp\" },\n \"output\": { \"language\": \"typescript\", \"framework\": \"express\" },\n \"success\": true,\n \"durationMs\": 245,\n \"error\": \"Error message if failed\",\n \"errorGuidance\": {\n \"hint\": \"Suggested fix\",\n \"resolution\": \"Step-by-step instructions\"\n }\n}\n```\n\nThe logging directory is validated at startup to ensure it's writable.\n\n\n### Policy System\n\nThe 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.\n\n**Default Behavior (No Configuration Needed):**\nBy default, all policies in the `policies/` directory are automatically discovered and merged:\n- `policies/security-baseline.rego` - Essential security rules (root user prevention, secrets detection, privileged containers)\n- `policies/base-images.rego` - Base image governance (Microsoft Azure Linux recommendation, no :latest tag, deprecated versions)\n- `policies/container-best-practices.rego` - Docker best practices (HEALTHCHECK, multi-stage builds, layer optimization)\n\nThis provides comprehensive out-of-the-box security and quality enforcement.\n\n### Policy Customization\n\nThe policy system supports four priority-ordered search paths for easy customization:\n\n**Priority Order (highest to lowest):**\n1. **Custom directory** via `CUSTOM_POLICY_PATH` environment variable (highest priority)\n2. **Project directory** at `/.containerization-assist/policy/` (tracked in git)\n3. **Global directory** at `~/.config/containerization-assist/policy/` (XDG-compliant)\n4. **Built-in `policies/`** (shipped with package, lowest priority)\n\n> **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.\n\n#### Quick Start\n\n```bash\n# Option 1: Global policies (no env var needed)\nmkdir -p ~/.config/containerization-assist/policy\n\n# Copy example policy from the npm package\ncp node_modules/containerization-assist-mcp/policies.user.examples/allow-all-registries.rego \\\n ~/.config/containerization-assist/policy/\n\n# Policies are auto-reloaded on the next tool execution β no restart needed\n```\n\nOr set a custom location in `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"ca\": {\n \"env\": {\n \"CUSTOM_POLICY_PATH\": \"/path/to/policies\"\n }\n }\n }\n}\n```\n\n#### Pre-Built Example Policies\n\nThe `policies.user.examples/` directory (included in the npm package) provides three ready-to-use examples:\n\n| Example | Purpose | Use Case |\n|---------|---------|----------|\n| `allow-all-registries.rego` | Override MCR preference | Docker Hub, GCR, ECR, private registries |\n| `warn-only-mode.rego` | Advisory-only enforcement | Testing, gradual adoption, dev environments |\n| `custom-organization-template.rego` | Organization template | Custom labels, registries, compliance |\n\nSee [policies.user.examples/README.md](policies.user.examples/README.md) for detailed usage.\n\n#### Built-In Policies\n\nThree production-ready Rego policies are included by default:\n\n- **`policies/security-baseline.rego`** - Essential security rules (root user prevention, secrets detection, privileged containers)\n- **`policies/base-images.rego`** - Base image governance (Microsoft Azure Linux recommendation, no :latest tag, deprecated versions)\n- **`policies/container-best-practices.rego`** - Docker best practices (HEALTHCHECK, multi-stage builds, layer optimization)\n\nUser policies override built-in policies by package namespace.\n\n**Policy File Format (Rego):**\n\n```rego\npackage containerization.custom_policy\n\n# Blocking violations\nviolations contains result if {\n input_type == \"dockerfile\"\n regex.match(`FROM\\s+[^:]+:latest`, input.content)\n\n result := {\n \"rule\": \"block-latest-tag\",\n \"category\": \"quality\",\n \"priority\": 80,\n \"severity\": \"block\",\n \"message\": \"Using :latest tag is not allowed. Specify explicit version tags.\",\n \"description\": \"Prevent :latest for reproducibility\",\n }\n}\n\n# Non-blocking warnings\nwarnings contains result if {\n input_type == \"dockerfile\"\n not regex.match(`HEALTHCHECK`, input.content)\n\n result := {\n \"rule\": \"suggest-healthcheck\",\n \"category\": \"quality\",\n \"priority\": 70,\n \"severity\": \"warn\",\n \"message\": \"Consider adding HEALTHCHECK instruction for container monitoring\",\n \"description\": \"HEALTHCHECK improves container lifecycle management\",\n }\n}\n\n# Policy decision\ndefault allow := false\nallow if count(violations) == 0\n\n# Result structure\nresult := {\n \"allow\": allow,\n \"violations\": violations,\n \"warnings\": warnings,\n \"suggestions\": [],\n \"summary\": {\n \"total_violations\": count(violations),\n \"total_warnings\": count(warnings),\n \"total_suggestions\": 0,\n },\n}\n```\n\n**Priority Levels:**\n- **90-100**: Security rules (highest priority)\n- **70-89**: Quality rules\n- **50-69**: Performance rules\n- **30-49**: Compliance rules\n\n**Using Policies:**\n\n```bash\n# List discovered policies\nnpx containerization-assist-mcp list-policies\n\n# List policies and show merged result\nnpx containerization-assist-mcp list-policies --show-merged\n\n# Validate Dockerfile with policies (automatic discovery)\nnpx containerization-assist-mcp fix-dockerfile --path ./Dockerfile\n```\n\n**Creating Custom Policies:**\n\nSee [Policy Customization Guide](docs/guides/policy-getting-started.md) and existing policies in `policies/` for examples.\n\n**Testing Policies:**\n\n```bash\n# Validate policy syntax\nopa check .containerization-assist/policy/my-policy.rego\n\n# Run policy tests\nopa test .containerization-assist/policy/\n\n# Test with MCP Inspector\nnpx @modelcontextprotocol/inspector containerization-assist-mcp start\n```\n\n### MCP Inspector (Testing)\n\n```bash\nnpx @modelcontextprotocol/inspector containerization-assist-mcp start\n```\n\n## Troubleshooting\n\n### Docker Connection Issues\n\n```bash\n# Check Docker is running\ndocker ps\n\n# Check socket permissions (Linux/Mac)\nls -la /var/run/docker.sock\n\n# For Windows, ensure Docker Desktop is running\n```\n\n### MCP Connection Issues\n\n```bash\n# Test with MCP Inspector\nnpx @modelcontextprotocol/inspector containerization-assist-mcp start\n\n# Check logs with debug level\nnpx -y containerization-assist-mcp start --log-level debug\n```\n\n### Kubernetes Connection Issues\n\nThe server performs fast-fail validation when Kubernetes tools are used. If you encounter Kubernetes errors:\n\n**Kubeconfig Not Found**\n```bash\n# Check if kubeconfig exists\nls -la ~/.kube/config\n\n# Verify kubectl can connect\nkubectl cluster-info\n\n# If using cloud providers, update kubeconfig:\n# AWS EKS\naws eks update-kubeconfig --name --region \n\n# Google GKE\ngcloud container clusters get-credentials --zone \n\n# Azure AKS\naz aks get-credentials --resource-group --name \n```\n\n**Connection Timeout or Refused**\n```bash\n# Verify cluster is running\nkubectl get nodes\n\n# Check API server address\nkubectl config view\n\n# Test connectivity to API server\nkubectl cluster-info dump\n\n# Verify firewall rules allow connection to API server port (typically 6443)\n```\n\n**Authentication or Authorization Errors**\n```bash\n# Check current context and user\nkubectl config current-context\nkubectl config view --minify\n\n# Test permissions\nkubectl auth can-i create deployments --namespace default\nkubectl auth can-i create services --namespace default\n\n# If using cloud providers, refresh credentials:\n# AWS EKS: re-run update-kubeconfig\n# GKE: run gcloud auth login\n# AKS: run az login\n```\n\n**Invalid or Missing Context**\n```bash\n# List available contexts\nkubectl config get-contexts\n\n# Set a context\nkubectl config use-context \n\n# View current configuration\nkubectl config view\n```\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n\n## Support\n\nSee [SUPPORT.md](SUPPORT.md) for information on how to get help with this project.\n\n## Trademarks\n\nThis 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](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks). 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.\n",
"bytes": 22902,
"sha": "7c6456af8adf20b028971e3f77eeb1d1bf63a132ca75bc2bae037a6e318a7ecd",
"repo_slug": "azure/containerization-assist",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_azure_containerization_assist_a4b9f679/readme"
}