Policypulse Mcp

PolicyPulse MCP

1 つの MCP サーバー。3 つのポリシーエンジン。コンテキストの切り替えは不要です。

PolicyPulse は OPA/Gatekeeper、Kyverno、Azure Policy を単一のインターフェースに統合します。これにより、あらゆる MCP 互換クライアントから、自然な言葉で実際のコンプライアンス状況を AI アシスタントに尋ねられます。

---

問題

最新の Kubernetes 環境では、複数のポリシーエンジンが同時に稼働します。

• OPA Gatekeeper — オンプレミスおよびハイブリッド環境でのアドミッション制御
• Kyverno — AKS、EKS、GKE 向けのポリシー・アズ・コード
• Azure Policy — Azure サブスクリプション全体にわたるコンプライアンススキャン

各エンジンはそれぞれ異なる API、違反の形式、コンプライアンスフレームワークとの対応付けを使用します。プラットフォームエンジニアは、「コンプライアンスを遵守できていますか？」という質問に答えるためだけに、3 つのダッシュボード、2 つの CLI、Azure Portal を行き来しています。

解決策

PolicyPulse は、3 つすべてのエンジンを 7 つの MCP ツールに統一します。AI アシスタントに次のように尋ねられます。

「すべてのエンジンの中で、最も重大な違反は何ですか？」 「このデプロイメントマニフェストを適用する前に確認してください。」 「どの違反が PCI-DSS の要件に該当しますか？」 「この違反について説明し、修正方法を教えてください。」

---

アーキテクチャ

MCP Clients (Claude, Cursor, GitHub Copilot, Cline, Windsurf, Continue.dev, Zed)
        │
        │  stdio (local)  ──or──  SSE over HTTPS (enterprise / Container Apps)
        ▼
┌───────────────────────────────────────┐
│           PolicyPulse MCP             │
│                                       │
│  ┌─────────────────────────────────┐  │
│  │      Intelligence Layer         │  │
│  │  risk summary · explain ·       │  │
│  │  prioritize · framework enrich  │  │
│  └──────────┬──────────────────────┘  │
│             │  Violation / Policy     │
│  ┌──────────┴──────────────────────┐  │
│  │       Normalized Schema         │  │
│  └──┬───────────┬──────────────┬───┘  │
│     │           │              │      │
│  ┌──┴──┐  ┌─────┴──┐  ┌───────┴──┐   │
│  │ GK  │  │Kyverno │  │  Azure   │   │
│  │     │  │        │  │  Policy  │   │
│  └──┬──┘  └────┬───┘  └────┬─────┘   │
└─────┼──────────┼───────────┼─────────┘
      │          │           │
   AKS/k8s    AKS/k8s    Azure Subscription
  Constraints PolicyReports  PolicyInsights API

コントロールカタログは唯一の信頼できる情報源です。CIS／PCI-DSS／NIST／SOC 2 の参照情報を実行時にライブの違反情報に追加する機能と、クラスターを必要とせずに YAML マニフェストをチェックするデプロイ前の静的ゲートの両方を支えます。

---

7 つの MCP ツール

ツール	機能
cluster_status	接続されているエンジン、クラスターごとの認証モードを含むフリート概要、認証情報の種類を表示します
list_policies	エンジン全体のすべてのポリシーを表示します。エンジンで絞り込めます
get_violations	フレームワーク参照情報を付加したすべての違反を表示します。名前空間／エンジン／重大度／クラスターで絞り込めます
get_compliance_risk_summary	規制上の影響を含む、エンジン横断のリスク概要を表示します
explain_violation	1 件の違反について、平易な言葉での説明、フレームワークとの対応付け、修正手順を提示します
check_manifest_compliance	デプロイ前の静的ゲートです。YAML を貼り付けると、クラスターなしで違反を取得できます
list_controls	CIS／PCI-DSS／NIST 800-53／SOC 2 との対応付けを含む、全 9 件のコントロールカタログを表示します

---

クイックスタート — デモモード

クラスターや Azure の認証情報は不要です。

git clone https://github.com/raviteja-pegata/policy-pulse-mcp
cd policy-pulse-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

POLICYPULSE_DEMO=true policy-pulse-mcp

---

AKS への接続

クラスターにポリシーエンジンをインストールする

# Kyverno
helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update
helm install kyverno kyverno/kyverno -n kyverno --create-namespace

# OPA Gatekeeper
helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts
helm install gatekeeper/gatekeeper --name-template=gatekeeper \
  -n gatekeeper-system --create-namespace

# Apply demo policies and workloads (wait 2-3 min for audit reports)
kubectl apply -f demo-cluster/kyverno-policies.yaml
kubectl apply -f demo-cluster/gatekeeper-policies.yaml
kubectl apply -f demo-cluster/non-compliant-workloads.yaml

クラスターに対して実行する

pip install -e ".[all]"
az aks get-credentials --resource-group <rg> --name <cluster>

AZURE_SUBSCRIPTION_ID=<sub-id> \
AZURE_CREDENTIAL_TYPE=cli \
policy-pulse-mcp

---

マルチクラスターのフリート

PolicyPulse は、1 回のセッションで複数のクラスターにクエリできます。すべての違反に cluster フィールドが含まれるため、クエリ時にクラスターで絞り込めます。

PolicyPulse のホスティング先に応じて、クラスターの指定方法は 2 通りあります。

モード	コンテキスト形式	使用する場面
Kubeconfig	label:context-name	ローカル開発、または Kubeconfig をポッドにマウントする場合
ワークロード ID	label:resourceGroup/clusterName	Container Apps または AKS でホストする場合。Kubeconfig ファイルは不要です

Kubeconfig モード（ローカル開発）

各クラスターの認証情報を取得し、1 つの Kubeconfig 内の複数のコンテキストを PolicyPulse に指定します。

az aks get-credentials --resource-group rg-prod --name aks-prod
az aks get-credentials --resource-group rg-staging --name aks-staging

POLICYPULSE_CLUSTERS=prod:aks-prod,staging:aks-staging \
AZURE_SUBSCRIPTION_ID=<sub-id> \
policy-pulse-mcp

コンテキスト名（aks-prod、aks-staging）は、~/.kube/config 内のコンテキスト名と一致している必要があります。

ワークロード ID モード（ホスト型デプロイ）

resourceGroup/clusterName 形式を使用します。PolicyPulse は Azure 管理 API を呼び出して各クラスターの API サーバー URL と CA 証明書を取得し、マネージド ID トークンで認証します。Kubeconfig ファイルはどこにも必要ありません。

POLICYPULSE_CLUSTERS=prod:rg-prod/aks-prod,staging:rg-staging/aks-staging \
AZURE_SUBSCRIPTION_ID=<sub-id> \
AZURE_CREDENTIAL_TYPE=managed_identity \
policy-pulse-mcp

詳しい設定手順については、以下のワークロード ID の設定セクションをご覧ください。

---

Azure Container Apps でのホスティング

エンタープライズ環境にデプロイする場合は、PolicyPulse を Azure Container Apps 上で SSE サーバーとして実行します。これにより、複数のチームやツールが HTTPS 経由で、1 つの一元管理されたコンプライアンスサーバーに接続できます。

stdio と SSE の比較

	stdio	SSE
トランスポート	ローカルパイプ	HTTP / HTTPS
クライアント	1 つ（ローカルプロセスのみ）	複数（同時接続）
認証	なし	ベアラートークン / Azure AD
ホスティング	開発者のノート PC のみ	Container Apps、AKS、任意のクラウド
最適な用途	ローカル開発、Claude Desktop	エンタープライズ、CI/CD、複数チーム

ステップ 1 — コンテナーをビルドしてプッシュする

docker build -t policypulse-mcp:latest .

az acr login --name <your-acr>
docker tag policypulse-mcp:latest <your-acr>.azurecr.io/policypulse-mcp:latest
docker push <your-acr>.azurecr.io/policypulse-mcp:latest

ステップ 2 — Container App を作成する

az containerapp create \
  --name policy-pulse-mcp \
  --resource-group <your-rg> \
  --environment <your-aca-environment> \
  --image <your-acr>.azurecr.io/policypulse-mcp:latest \
  --target-port 8000 \
  --ingress external \
  --env-vars \
    POLICYPULSE_TRANSPORT=sse \
    AZURE_SUBSCRIPTION_ID=<sub-id> \
    AZURE_CREDENTIAL_TYPE=managed_identity \
    POLICYPULSE_CLUSTERS=prod:rg-prod/aks-prod,staging:rg-staging/aks-staging

POLICYPULSE_CLUSTERS に resourceGroup/clusterName 形式を使用すると、Workload Identity モードが有効になります。コンテナー内に kubeconfig ファイルは必要ありません。

ステップ 3 — マネージド ID を割り当てる

az containerapp identity assign \
  --name policy-pulse-mcp \
  --resource-group <your-rg> \
  --system-assigned

PRINCIPAL_ID=$(az containerapp identity show \
  --name policy-pulse-mcp \
  --resource-group <your-rg> \
  --query principalId -o tsv)

次に、Workload Identity のセットアップのセクションに従い、各 AKS クラスターへのアクセス権を ID に付与します。

ステップ 4 — ネットワーク接続

PolicyPulse が Container Apps から各 AKS API サーバーにアクセスできる必要があります。

# Option A: VNet integration (recommended for production)
# Create the Container Apps environment on the same VNet as your AKS clusters.
az containerapp env create \
  --name policy-pulse-env \
  --resource-group <your-rg> \
  --location eastus \
  --infrastructure-subnet-resource-id <subnet-id>

# Option B: Public AKS — whitelist the Container App outbound IP
ACA_IP=$(az containerapp show \
  --name policy-pulse-mcp \
  --resource-group <your-rg> \
  --query properties.outboundIpAddresses[0] -o tsv)

az aks update \
  --name aks-prod \
  --resource-group rg-prod \
  --api-server-authorized-ip-ranges $ACA_IP

SSE エンドポイントは次のとおりです。

https://policy-pulse-mcp.<unique-id>.eastus.azurecontainerapps.io/sse

---

Workload Identity のセットアップ

このセクションでは、resourceGroup/clusterName 形式のクラスターに必要なすべての設定について説明します。この方法は、Container Apps および AKS でホストするデプロイに推奨されます。

仕組み

PolicyPulse が POLICYPULSE_CLUSTERS=prod:rg-prod/aks-prod を検出すると、次の処理を行います。

1. 管理プレーンのトークンを使って Azure 管理 API を呼び出し、クラスターの API サーバー URL と CA 証明書を取得します。
2. AKS AAD サーバーアプリケーションを対象とする 2 つ目のトークンを取得します（オーディエンスは 6dae42f8-4368-4678-94ff-3960e28e3630）。
3. これら 2 つの情報から Kubernetes クライアントを構築します。kubeconfig ファイルはどこにも必要ありません。

PolicyPulse (Container App or AKS pod)
        │
        │  managed identity token
        ▼
Azure AD
        │
        ├──► management.azure.com  →  listClusterUserCredential
        │                             (gets API server URL + CA cert)
        │
        └──► AKS API server (each cluster)
             "I am identity X — is my token valid?"
             "Yes — you have view access — here are your violations"

前提条件

• 対象となる各 AKS クラスターで AAD 統合が有効になっている必要があります。2021 年以降に作成されたクラスターでは、これがデフォルトです。確認するには次のコマンドを実行します。

  az aks show --resource-group rg-prod --name aks-prod \
    --query "aadProfile" -o json
  # Should return a non-null object
  

• マネージド ID には、2 つのレベルでの権限が必要です。クラスターの認証情報を取得するための Azure 管理プレーンと、ポリシーリソースを読み取るための各 Kubernetes クラスター内です。

ステップ 1 — 管理プレーンの権限を付与する

ID には、各対象クラスターで listClusterUserCredential を呼び出す権限と、Azure Policy のコンプライアンス状態を読み取る権限が必要です。

PRINCIPAL_ID=<principal-id-of-your-managed-identity>
SUB_ID=<your-subscription-id>

# Azure Policy — read compliance state across the subscription
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Policy Insights Data Reader (Preview)" \
  --scope /subscriptions/$SUB_ID

# AKS — fetch cluster credentials (repeat for each target cluster)
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Azure Kubernetes Service Cluster User Role" \
  --scope /subscriptions/$SUB_ID/resourceGroups/rg-prod/providers/Microsoft.ContainerService/managedClusters/aks-prod

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Azure Kubernetes Service Cluster User Role" \
  --scope /subscriptions/$SUB_ID/resourceGroups/rg-staging/providers/Microsoft.ContainerService/managedClusters/aks-staging

ステップ 2 — 各クラスターで Kubernetes RBAC を付与する

管理プレーンのトークンによって PolicyPulse が API サーバーにアクセスできるようになっても、Kubernetes は引き続き独自の RBAC を確認します。クラスターが Azure RBAC と ローカル RBAC のどちらを使用しているかによって、方法が異なります。

クラスターで使用しているモードを確認します。

az aks show --resource-group rg-prod --name aks-prod \
  --query "aadProfile.enableAzureRbac" -o tsv
# true = Azure RBAC mode, false/null = local RBAC mode

Azure RBAC モード（新しいクラスターに推奨）：

Azure RBAC のロールは Kubernetes RBAC に直接マッピングされるため、クラスター内で kubectl コマンドを実行する必要はありません。

# Grant read access to Gatekeeper and Kyverno resources (repeat per cluster)
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Azure Kubernetes Service RBAC Reader" \
  --scope /subscriptions/$SUB_ID/resourceGroups/rg-prod/providers/Microsoft.ContainerService/managedClusters/aks-prod

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Azure Kubernetes Service RBAC Reader" \
  --scope /subscriptions/$SUB_ID/resourceGroups/rg-staging/providers/Microsoft.ContainerService/managedClusters/aks-staging

ローカル RBAC モード（古いクラスター）：

各クラスター内で、ID の クライアント ID（プリンシパル ID／オブジェクト ID ではありません）を使って ClusterRoleBinding を作成する必要があります。

# Get the client ID of the managed identity
CLIENT_ID=$(az identity show \
  --name <your-managed-identity-name> \
  --resource-group <your-rg> \
  --query clientId -o tsv)

# Run this for each target cluster
az aks get-credentials --resource-group rg-prod --name aks-prod

kubectl create clusterrolebinding policypulse-reader \
  --clusterrole=view \
  --user="$CLIENT_ID"

view ClusterRole は、Gatekeeper と Kyverno が違反を記録するカスタムリソースを含む、ほとんどのリソースへの読み取り専用アクセスを許可します。

ステップ 3 — PolicyPulse を設定する

Container App またはポッドに、次の環境変数を設定します。

AZURE_SUBSCRIPTION_ID    = <your-subscription-id>
AZURE_CREDENTIAL_TYPE    = managed_identity
POLICYPULSE_CLUSTERS     = prod:rg-prod/aks-prod,staging:rg-staging/aks-staging

ユーザー割り当てマネージド ID の場合は、次の設定も行います。

AZURE_CLIENT_ID          = <client-id-of-the-user-assigned-identity>

ステップ 4 — 接続を確認する

サーバーの実行後、cluster_status を呼び出します。応答には、各クラスターの認証モードが表示されます。

{
  "fleet": [
    { "label": "prod",    "context": "rg-prod/aks-prod",       "auth": "workload_identity" },
    { "label": "staging", "context": "rg-staging/aks-staging", "auth": "workload_identity" }
  ]
}

"auth" に "workload_identity" と表示され、クラスターが connected_engines に含まれていれば、セットアップは完了です。

トラブルシューティング

症状	考えられる原因	解決方法
AZURE_SUBSCRIPTION_ID must be set	環境変数が設定されていません	AZURE_SUBSCRIPTION_ID を設定します
管理 API からの 403	Cluster User Role がありません	ステップ 1 のロール割り当てを実行します
k8s API からの 401 Unauthorized	k8s RBAC がありません	クラスターでステップ 2 を実行します
aadProfile is null	AAD 統合が有効になっていません	az aks update --enable-aad で有効にします
No CA certificate found	kubeconfig に CA が含まれていません	クラスターの状態を確認します。フォールバックでは、検証されていない TLS を使用します

---

MCP クライアントの設定

Claude Desktop — ローカル（stdio）

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "policy-pulse": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "policy_pulse_mcp.server"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "your-sub-id",
        "AZURE_CREDENTIAL_TYPE": "cli"
      }
    }
  }
}

Claude Desktop — エンタープライズ（SSE）

{
  "mcpServers": {
    "policy-pulse": {
      "url": "https://policy-pulse-mcp.<unique-id>.eastus.azurecontainerapps.io/sse"
    }
  }
}

Cursor

Settings → MCP → Add Server を開きます：

{
  "policy-pulse": {
    "command": "python",
    "args": ["-m", "policy_pulse_mcp.server"],
    "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
  }
}

エンタープライズ SSE の場合：{ "url": "https://..." }

GitHub Copilot（VS Code）

ワークスペースの .vscode/mcp.json に追加します：

{
  "servers": {
    "policy-pulse": {
      "type": "sse",
      "url": "https://policy-pulse-mcp.<unique-id>.eastus.azurecontainerapps.io/sse"
    }
  }
}

ローカルの stdio の場合：

{
  "servers": {
    "policy-pulse": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "policy_pulse_mcp.server"],
      "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
    }
  }
}

Continue.dev

~/.continue/config.json：

{
  "mcpServers": [
    {
      "name": "policy-pulse",
      "command": "python",
      "args": ["-m", "policy_pulse_mcp.server"],
      "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
    }
  ]
}

Cline（VS Code）

Cline 拡張機能 → MCP Servers → Add：

{
  "policy-pulse": {
    "command": "python",
    "args": ["-m", "policy_pulse_mcp.server"],
    "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
  }
}

Windsurf（Codeium）

Windsurf Settings → MCP → Add server：

{
  "policy-pulse": {
    "serverType": "stdio",
    "command": "python",
    "args": ["-m", "policy_pulse_mcp.server"],
    "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
  }
}

Zed Editor

~/.config/zed/settings.json：

{
  "context_servers": {
    "policy-pulse": {
      "command": {
        "path": "python",
        "args": ["-m", "policy_pulse_mcp.server"],
        "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
      }
    }
  }
}

---

環境変数

コア

変数	デフォルト	説明
POLICYPULSE_DEMO	false	true = モックデータを使用します。クラスターや Azure の認証情報は不要です
POLICYPULSE_TRANSPORT	stdio	ローカルクライアントには stdio、ホスト型デプロイには sse を指定します
POLICYPULSE_HOST	0.0.0.0	SSE サーバーのバインドアドレス
PORT	8000	SSE サーバーのポート（POLICYPULSE_PORT も指定できます）
POLICYPULSE_LOG	INFO	ログレベル（DEBUG、INFO、WARNING）

Kubernetes

変数	デフォルト	説明
KUBECONFIG	~/.kube/config	kubeconfig ファイルへのパス（kubeconfig モードでのみ使用）
POLICYPULSE_CLUSTERS	（単一クラスター）	カンマ区切りのリストです。次の 2 つの形式に対応しています：label:context-name（kubeconfig モード）または label:resourceGroup/clusterName（ワークロード ID モード）。例：prod:rg-prod/aks-prod,dev:aks-dev-context

Azure

変数	必須	説明
AZURE_SUBSCRIPTION_ID	Azure Policy とワークロード ID に必要	ポリシーのコンプライアンスを照会するサブスクリプション
AZURE_CREDENTIAL_TYPE	いいえ（デフォルト：auto）	auto | cli | managed_identity | service_principal
AZURE_TENANT_ID	service_principal の場合に必要	Azure AD テナント ID
AZURE_CLIENT_ID	service_principal またはユーザー割り当て MI の場合に必要	クライアント ID または ID
AZURE_CLIENT_SECRET	service_principal の場合に必要	クライアントシークレット

---

Azure 認証情報の種類

ローカル開発：

az login
AZURE_CREDENTIAL_TYPE=cli policy-pulse-mcp

CI/CD — サービスプリンシパル：

AZURE_CREDENTIAL_TYPE=service_principal \
AZURE_TENANT_ID=<tenant-id> \
AZURE_CLIENT_ID=<client-id> \
AZURE_CLIENT_SECRET=<secret> \
policy-pulse-mcp

Container Apps / AKS での本番環境 — マネージド ID：

AZURE_CREDENTIAL_TYPE=managed_identity policy-pulse-mcp

マネージド ID に必要な Azure ロール：

ロール	スコープ	用途
Policy Insights Data Reader (Preview)	サブスクリプション	Azure Policy のコンプライアンス状態を読み取ります
Azure Kubernetes Service Cluster User Role	各 AKS クラスター	管理 API 経由でクラスターの認証情報を取得します
Azure Kubernetes Service RBAC Reader	各 AKS クラスター	Gatekeeper/Kyverno リソースを読み取ります（Azure RBAC クラスター）

Azure RBAC の代わりにローカル RBAC を使用するクラスターについては、ワークロード ID の設定のステップ 2 を参照してください。

---

インストール

pip install policy-pulse-mcp                      # core only (demo + static gate)
pip install "policy-pulse-mcp[kubernetes]"        # + Gatekeeper + Kyverno
pip install "policy-pulse-mcp[azure]"             # + Azure Policy
pip install "policy-pulse-mcp[all]"               # everything

ソースから：

git clone https://github.com/raviteja-pegata/policy-pulse-mcp
cd policy-pulse-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"

---

開発

git clone https://github.com/raviteja-pegata/policy-pulse-mcp
cd policy-pulse-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all,dev]"

make test          # 87 tests, fully offline, ~0.3s
make demo-server   # POLICYPULSE_DEMO=true
make lint
make fmt

---

ロードマップ

v0.2

• get_violation_history — 時間経過に伴うコンプライアンスのドリフト
• check_resource_compliance — 特定の Azure リソースに対するポイントクエリ
• Azure の複数サブスクリプションへの対応
• クラスター内デプロイ用 Helm チャート
• PyPI への公開

v0.3

• YAML 駆動のカタログ拡張 — Python を書かずにコントロールを追加
• search_catalog ツール
• GitHub Actions のデプロイ前ゲートの例

v1.0

• generate_remediation_manifest
• create_exemption_request
• trigger_azure_remediation_task

---

License

MIT — see LICENSE.