mcp-deploy-intel

Kubernetes deployment intelligence — typed query tools + AI-synthesised risk briefs. CLI + MCP server.

Record every rollout, score outcomes automatically, and get LLM-authored risk briefs before you promote to production. Works as a standalone CLI, a Model Context Protocol (MCP) server for Claude Desktop / Claude Code / any MCP client, a Docker image, a Helm chart (in-cluster watcher + evaluator Deployment), and a GitHub Action (pre-promote gate).

• Status: v1.0.0 — production-ready.
• PyPI: mcp-deploy-intel
• Image: ghcr.io/vellankikoti/mcp-deploy-intel:v1.0.0 (multi-arch, cosign keyless-signed)
• Source: this repo
• License: Apache-2.0

Table of contents

1. What it does — the 9 tools
2. Install
3. Quickstart — one-liners
4. CLI reference
5. Watcher + evaluator lifecycle
6. MCP server — Claude Desktop / Claude Code setup
7. LLM configuration
8. GitHub Action — pre-promote gate
9. Helm chart — in-cluster Deployment
10. Verify the container signature (cosign)
11. Exit codes
12. Troubleshooting
13. Design & plans
14. Development

What it does — the 9 tools

All tools are available via CLI, MCP, and the composite GitHub Action.

Run deploy-intel --help to see all commands. All 9 tools are also exposed via the MCP server.

Install

Pick the one that matches how you want to use it. No setup step is required beyond installing the tool itself.

A. Run ephemerally via uvx (recommended for one-off queries)

# Install uv if you don't have it (macOS/Linux):
curl -LsSf https://astral.sh/uv/install.sh | sh

# Then run the tool without installing:
uvx mcp-deploy-intel list-workloads-in-namespace default

uvx downloads the package and runs it in an isolated env. Nothing sticks to your global Python.

B. Install with pip / uv pip (if you want it on PATH)

pip install mcp-deploy-intel        # system/user pip
# or
uv pip install mcp-deploy-intel     # uv's pip (faster)

Then: deploy-intel --help.

C. Docker image (cosign-signed, multi-arch)

docker pull ghcr.io/vellankikoti/mcp-deploy-intel:v1.0.0

docker run --rm \
  -v ~/.kube/config:/home/di/.kube/config:ro \
  -e KUBECONFIG=/home/di/.kube/config \
  ghcr.io/vellankikoti/mcp-deploy-intel:v1.0.0 \
  list-workloads-in-namespace default

macOS + kind note: the container's 127.0.0.1 doesn't point to the kind API server on the host. Use a remote cluster or use the CLI directly (uvx / pip) against local kind.

D. Helm chart (in-cluster watcher + evaluator Deployment)

See Helm chart — in-cluster Deployment below.

E. GitHub Action (pre-promote gate)

See GitHub Action — pre-promote gate below.

Quickstart — one-liners

Point kubectl at your cluster first (any cluster: kind, EKS, GKE, AKS, bare-metal). deploy-intel uses your current kubeconfig context unless you pass --context or --kubeconfig.

# 1. List all workloads in a namespace
uvx mcp-deploy-intel list-workloads-in-namespace default

# 2. Snapshot a single workload in Markdown
uvx mcp-deploy-intel get-workload default/Deployment/my-api --format md

# 3. Start the watcher — records every new rollout to SQLite
deploy-intel watch --namespace prod --db-path /tmp/deploy.db

# 4. Run the evaluator — scores in_progress deploys every 60 s
deploy-intel evaluate --db-path /tmp/deploy.db --no-llm

# 5. Get the deploy history for a workload
deploy-intel get-deploy-history default Deployment my-api --db-path /tmp/deploy.db

# 6. Generate an AI risk brief before promoting
deploy-intel risk-brief default/Deployment/my-api \
  --target-image my-api:v2.3.1 \
  --db-path /tmp/deploy.db \
  --format md

CLI reference

All commands share these global behaviours:

• Default kubeconfig: $KUBECONFIG env var, falling back to ~/.kube/config.
• Default context: whatever kubectl config current-context would return.
• Exit codes: see Exit codes.

list-workloads-in-namespace — namespace inventory

deploy-intel list-workloads-in-namespace <namespace> [--context TEXT] [--kubeconfig PATH]

get-workload — single workload snapshot

deploy-intel get-workload <namespace>/<kind>/<name> [--context TEXT] [-f md|json]

watch — K8s informer loop

deploy-intel watch [--namespace NS]... [--context TEXT] [--kubeconfig PATH] [--db-path PATH]

Streams Deployment and StatefulSet events. Deduplicates by (uid, generation). Inserts one DeployRecord per new rollout. Uses exponential backoff (1–60 s) on reconnect; honours SIGINT/SIGTERM.

evaluate — scoring loop

deploy-intel evaluate [--window-s N] [--interval-s N] [--prom-url URL] [--db-path PATH] [--no-llm]

Picks up in_progress deploys older than window-s seconds, fetches a post-snapshot, optionally queries Prometheus error rates, and writes the final status back to SQLite:

record-deploy — manual deploy capture

deploy-intel record-deploy <namespace> <kind> <name> <revision> <image> [--actor TEXT] [--commit-sha TEXT] [--db-path PATH]

get-deploy-history — query history

deploy-intel get-deploy-history <namespace> <kind> <name> [--limit N] [--db-path PATH]

get-rollback-history — query rollbacks

deploy-intel get-rollback-history <namespace> <kind> <name> [--limit N] [--db-path PATH]

risk-brief — AI risk assessment

deploy-intel risk-brief <namespace>/<kind>/<name> --target-image <image>
  [--prom-url URL] [--llm-provider TEXT] [--llm-base-url TEXT] [--llm-api-key TEXT]
  [--no-llm] [--db-path PATH] [-f md|json]

Fans out in parallel to get_workload, get_metric_trend, get_inbound_traffic, get_deploy_history, and get_rollback_history; assembles evidence; calls the LLM for a structured RiskBrief; falls back to rule-based scoring when offline.

serve-mcp — run the MCP stdio server

deploy-intel serve-mcp

Intended to be wired into an MCP client (Claude Desktop, Claude Code, any MCP-compatible tool). Exposes all 9 tools.

Watcher + evaluator lifecycle

The watcher and evaluator are designed to run as a pair — either locally in two terminals, or as a two-container Deployment in cluster.

                 ┌──────────────┐
  K8s events ──► │   watcher    │ ──► SQLite (history.db)
                 └──────────────┘          │
                                           │ (shared PVC / shared path)
                 ┌──────────────┐          │
  every 60 s ──► │  evaluator   │ ◄────────┘
                 └──────────────┘
                       │
                       ▼
               ROLLED_BACK / DEGRADED / SUCCESS / UNKNOWN

Both containers run as UID 10001, read-only root filesystem, with no extra Linux capabilities.

MCP server — Claude Desktop / Claude Code setup

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "deploy-intel": {
      "command": "uvx",
      "args": ["mcp-deploy-intel", "serve-mcp"],
      "env": {
        "DEPLOY_INTEL_LLM_PROVIDER": "anthropic/claude-sonnet-4-6"
      }
    }
  }
}

Restart Claude Desktop. In a conversation, these tools become available:

• list_workloads_in_namespace(namespace) — namespace inventory.
• get_workload(namespace, kind, name) — single workload snapshot.
• get_metric_trend(promql, window) — TimeSeries for any PromQL query.
• get_inbound_traffic(namespace, kind, name) — upstream callers.
• get_outbound_traffic(namespace, kind, name) — downstream callees.
• record_deploy(namespace, kind, name, revision, image, ...) — manual capture.
• get_deploy_history(namespace, kind, name) — full history.
• get_rollback_history(namespace, kind, name) — rollback subset.
• generate_risk_brief(namespace, kind, name, target_image) — AI risk brief.

Example prompt: "Give me a risk brief for the checkout Deployment in the prod namespace before I promote to v2.3.1."

Claude Code

Add to the MCP servers section of your Claude Code config (~/.config/claude-code/mcp.json or equivalent):

{
  "mcpServers": {
    "deploy-intel": {
      "command": "uvx",
      "args": ["mcp-deploy-intel", "serve-mcp"]
    }
  }
}

Any other MCP client

The server speaks MCP over stdio. Invoke deploy-intel serve-mcp and send JSON-RPC on stdin. All 9 tools are exposed.

LLM configuration

mcp-deploy-intel is LLM-agnostic via litellm + instructor. Works with any provider, any URL, or fully offline.

Precedence (highest wins): CLI flag → environment variable → default.

Anthropic (Claude)

export DEPLOY_INTEL_LLM_PROVIDER=anthropic/claude-sonnet-4-6
export DEPLOY_INTEL_LLM_API_KEY=sk-ant-...
deploy-intel risk-brief prod/Deployment/api --target-image api:v2

OpenAI

export DEPLOY_INTEL_LLM_PROVIDER=openai/gpt-4o
export DEPLOY_INTEL_LLM_API_KEY=sk-...

Local Ollama

ollama serve &
ollama pull qwen2.5:7b

export DEPLOY_INTEL_LLM_PROVIDER=ollama/qwen2.5:7b
export DEPLOY_INTEL_LLM_BASE_URL=http://localhost:11434

Fully offline (no LLM calls)

deploy-intel risk-brief ... --no-llm
# or
export DEPLOY_INTEL_OFFLINE=1

Offline mode uses deterministic rule-based scoring derived from deploy history, replica counts, and Prometheus error rates.

GitHub Action — pre-promote gate

The repo ships a composite GitHub Action. Use it as a pre-promote check in your release workflow.

# .github/workflows/pre-promote.yml
name: pre-promote
on:
  workflow_dispatch:
    inputs:
      image:
        required: true
      target-ref:
        required: true
jobs:
  risk-brief:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure kubectl
        run: |
          mkdir -p ~/.kube
          echo "${{ secrets.KUBECONFIG }}" > ~/.kube/config
          chmod 600 ~/.kube/config

      - uses: vellankikoti/mcp-deploy-intel@v1.0.0
        with:
          namespace: prod
          workload: Deployment/api
          target-image: ${{ github.event.inputs.image }}
          fail-on: blocker
          offline: "true"

      - name: Upload risk brief
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: risk-brief
          path: risk-brief.md

Inputs (see action.yml):

namespace, workload, target-image, kubeconfig, context, prom-url, fail-on, llm-provider, llm-api-key, offline, db-path, format, image.

Outputs:

• report-path: absolute path to the risk brief file.
• overall-risk: low / medium / high / blocker / unknown.

Helm chart — in-cluster Deployment

Install a two-container Deployment (watcher + evaluator) that records every rollout and scores outcomes continuously.

git clone https://github.com/vellankikoti/mcp-deploy-intel.git
cd mcp-deploy-intel

helm install deploy-intel ./charts/deploy-intel \
  --namespace deploy-intel --create-namespace \
  --set image.tag=v1.0.0

Key values (see charts/deploy-intel/values.yaml for full list):

Query the in-cluster history:

# Exec into the watcher container:
kubectl exec -n deploy-intel deploy/deploy-intel -c watcher -- \
  deploy-intel get-deploy-history <namespace> <kind> <name> \
  --db-path /var/lib/deploy-intel/history.db

Enable LLM risk briefs in-cluster:

kubectl -n deploy-intel create secret generic llm-api \
  --from-literal=api-key=sk-ant-...

helm upgrade deploy-intel ./charts/deploy-intel \
  --namespace deploy-intel \
  --set llm.offline=false \
  --set llm.provider=anthropic/claude-sonnet-4-6 \
  --set llm.secretName=llm-api

Verify the container signature (cosign)

The image is signed with keyless OIDC via Sigstore. Anyone can verify:

# Install cosign: https://docs.sigstore.dev/cosign/system_config/installation/
brew install cosign   # or the equivalent

cosign verify ghcr.io/vellankikoti/mcp-deploy-intel:v1.0.0 \
  --certificate-identity-regexp="https://github.com/vellankikoti/mcp-deploy-intel/.github/workflows/release.yml@refs/tags/v1.0.0" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com"

Expected: Verification for ... — The following checks were performed: ....

A CycloneDX SBOM is attached to every GitHub Release as an asset (sbom-vX.Y.Z.cdx.json).

Exit codes

Troubleshooting

command not found: deploy-intel after pip install — the binary is installed into your venv's bin/. Activate the venv, or use uvx instead.

kubeconfig not found — pass --kubeconfig /path/to/config explicitly, or export KUBECONFIG=/path/to/config. Clouds (EKS/GKE/AKS) need their auth-helper binary on $PATH (aws-cli, gcloud, kubelogin respectively). The Docker image bundles these.

Prometheus query failed: connection refused — --prom-url points somewhere unreachable. Without --prom-url, Prometheus-requiring tools return status="skip" with a clear reason.

generate_risk_brief returns overall_risk=unknown with no LLM — pass --no-llm to get the deterministic fallback. With --no-llm, the brief uses rule-based scoring from deploy history and replica counts.

LLM error: model not found — check DEPLOY_INTEL_LLM_PROVIDER is set to a valid litellm provider string (e.g. anthropic/claude-sonnet-4-6). For Ollama, confirm the model is pulled (ollama list).

Container can't reach my local kind cluster — kind binds its API server to 127.0.0.1:<port> on your host; inside Docker, 127.0.0.1 is the container, not the host. Use the CLI directly (uvx / pip) for local kind, or point at a remote cluster.

watcher pod stuck in Pending — check PVC binding: kubectl -n deploy-intel get pvc. If your cluster has no default StorageClass, set persistence.storageClass in values or persistence.enabled=false (uses emptyDir instead).

Design & plans

• Design spec: docs/superpowers/specs/2026-04-21-mcp-deploy-intel-design.md
• Implementation plans: docs/superpowers/plans/ — seven plans, v0.1.0 walking-skeleton → v1.0.0 production release.
• Workshop path (1–3 hours, hands-on): docs/workshop.md
• Changelog: CHANGELOG.md

Development

git clone https://github.com/vellankikoti/mcp-deploy-intel.git
cd mcp-deploy-intel

# Install uv (https://docs.astral.sh/uv/)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Set up env
uv venv
uv pip install -e ".[dev]"

# Run quality gates
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest -m "not integration and not golden and not mcp_contract" -v   # unit (fast)

# Helm chart tests (needs helm on PATH)
uv run pytest tests/helm/ -v

# Action metadata tests
uv run pytest tests/action/ -v

# Workflow tests
uv run pytest tests/workflows/ -v

# Golden + integration tests against an ephemeral kind cluster (needs Docker)
uv run pytest -m golden -v
uv run pytest -m integration -v

# Helm lint
helm lint charts/deploy-intel

Adding a tool:

1. Implement in src/deploy_intel/tools/<tool_name>.py.
2. Register via @mcp.tool() in src/deploy_intel/server.py.
3. Add CLI subcommand in src/deploy_intel/cli.py.
4. Add unit tests under tests/unit/test_tool_<name>.py.
5. Update this README's tool table.

Built for a talk/workshop on safely giving AI agents real Kubernetes capabilities. The full story is in docs/superpowers/specs/.