Containerization Assist

Containerization Assist MCP サーバー

VS Code やその他の MCP 互換ツールを通じて、Docker コンテナーのビルド、スキャン、デプロイを支援する AI 搭載のコンテナー化アシスタントです。

ドキュメント全文 →

インストール

機能

主な機能

• 🐳 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"
      }
    }
  }
}

GitHub Copilot で MCP サーバーを有効にするには、VS Code を再起動してください。

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 クライアント：Copilot を備えた VS Code、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"

単一オペレーター向けモデル

このサーバーは、1 人のエンジニアが一度に 1 つのアプリケーションをコンテナー化する用途に最適化されています。主な特徴は次のとおりです。

• 順次実行：各ツールは、前の手順の結果を基に処理します
• 迅速な失敗検出：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 が含まれます。このラベルは、生成された Dockerfile の LABEL 命令として含まれます。

ラベル	値	用途
com.azure.containerizationassist.version	パッケージのバージョン（例：1.4.0）	使用された containerization-assist のバージョン

Kubernetes マニフェスト（generate-k8s-manifests）：

ツールの出力には、生成されたすべての Kubernetes リソースのメタデータに適用される attributionLabels.annotations が含まれます。

種類	キー	値	用途
アノテーション	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 (60s)	いいえ
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、マルチステージビルド、レイヤーの最適化）

これにより、導入直後から包括的なセキュリティと品質の適用が可能になります。

ポリシーのカスタマイズ

ポリシーシステムでは、優先順位の高い順に検索される4つのパスをサポートしており、簡単にカスタマイズできます：

優先順位（高い順）：

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 パッケージに含まれています）には、すぐに使える3つの例が用意されています。

例	目的	ユースケース
allow-all-registries.rego	MCR の優先設定を上書き	Docker Hub、GCR、ECR、プライベートレジストリ
warn-only-mode.rego	警告のみの適用	テスト、段階的な導入、開発環境
custom-organization-template.rego	組織向けテンプレート	カスタムラベル、レジストリ、コンプライアンス

詳しい使い方については、policies.user.examples/README.md をご覧ください。

組み込みポリシー

本番環境ですぐに使える3つの 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 - 詳細については LICENSE ファイルをご覧ください。

サポート

このプロジェクトのサポートを受ける方法については、SUPPORT.md をご覧ください。

商標

このプロジェクトには、プロジェクト、製品、またはサービスの商標やロゴが含まれている場合があります。Microsoft の商標またはロゴの正規の使用は、Microsoft 商標およびブランドガイドラインに従う必要があります。このプロジェクトの変更版で Microsoft の商標またはロゴを使用する場合、混乱を招いたり、Microsoft の後援を暗示したりしてはなりません。第三者の商標またはロゴの使用は、それぞれの第三者のポリシーに従うものとします。