You: What applications are failing in production?

Claude: Let me check the production applications for you.

[calls list_applications(health_status="Degraded", project="prod")]

Found 2 application(s):

- payment-service [prod] health=Degraded sync=OutOfSync dest=payments@https://prod.k8s...
- notification-api [prod] health=Degraded sync=Synced dest=notifications@https://prod.k8s...

The payment-service is both unhealthy AND out of sync. Want me to diagnose what's wrong?

You: Why is payment-service broken?

Claude: I'll run a full diagnosis.

[calls diagnose_sync_failure(name="payment-service")]

Diagnosis for 'payment-service':

Found 4 issue(s):
  - Application is out of sync (revision: abc123f)
  - [SyncError] Failed to sync: resource payment-deployment: container crashed
  - Image pull failed: ImagePullBackOff for payments:v2.3.1
  - Found 2 unhealthy resources in resource tree
    - Deployment/payment-deployment: Container crashloopbackoff
    - Pod/payment-deployment-7f8b9-x2k4j: CrashLoopBackOff

Suggestions:
  - Verify image exists and registry credentials are configured
  - Check pod logs for application startup errors
  - Run get_application_diff to see pending changes

The image tag v2.3.1 doesn't seem to exist. Can you verify it was pushed to the registry?

You: Show me what would change if I sync it

Claude: [calls get_application_diff(name="payment-service")]

Diff for application 'payment-service':

Resources to UPDATE (3):
  ~ Deployment/payment-deployment
  ~ ConfigMap/payment-config
  ~ Service/payment-service

Resources in sync: 12

The sync would update the deployment (probably the image tag fix), update the
config, and touch the service. Want me to run the sync?

You: Yes, sync it

Claude: [calls sync_application(name="payment-service", dry_run=false)]

Sync initiated for 'payment-service'
Revision: HEAD
Prune: false

Use get_application_status to monitor progress.

I'll check the status in a moment to confirm it's progressing.

# Bad (what most tools return)
Error: exit status 1

# Good (what we return)
ArgoCD API error (403): Application payment-service not found in project 'default'

Suggestions:
  - Check if application exists: list_applications(project="prod")
  - Verify you have access to the target project

# Clone the repository
git clone https://github.com/peopleforrester/mcp-k8s-observability-argocd-server
cd mcp-k8s-observability-argocd-server

# Install with uv
uv sync

{
  "mcpServers": {
    "argocd": {
      "type": "stdio",
      "command": "/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-k8s-observability-argocd-server",
        "argocd-mcp"
      ],
      "env": {
        "ARGOCD_URL": "https://argocd.example.com",
        "ARGOCD_TOKEN": "your-api-token",
        "ARGOCD_INSECURE": "false"
      }
    }
  }
}

# Build the image
docker build -t argocd-mcp-server .

# Run with environment variables
docker run -e ARGOCD_URL=https://argocd.example.com \
           -e ARGOCD_TOKEN=your-token \
           argocd-mcp-server:latest

# Set environment variables
export ARGOCD_URL=https://argocd.example.com
export ARGOCD_TOKEN=your-token

# Run the server
uv run argocd-mcp

# Enable writes (still blocks destructive operations)
export MCP_READ_ONLY=false

# Enable destructive operations (delete, prune) - DANGER ZONE
export MCP_DISABLE_DESTRUCTIVE=false

list_applications(health_status="Degraded", project="prod")

diagnose_sync_failure(name="my-app")

sync_application(name="my-app", dry_run=false)

get_application_diff(name="my-app")

get_application_history(name="my-app", limit=20)

# Primary instance
export ARGOCD_URL=https://argocd-prod.example.com
export ARGOCD_TOKEN=prod-token

# Additional instances can be configured via the multi-env example.
# See examples/claude-desktop-multi-env.json

# Install dependencies
uv sync --dev

# Run tests
uv run pytest

# Run linting
uv run ruff check src tests
uv run mypy src

# Build Docker image
docker build -t argocd-mcp-server .

docker info | grep "Cgroup Version"

# Auto-detect cgroup version and create cluster
./scripts/setup-test-cluster.sh

# Or manually with specific version:
# For cgroups v2 (recommended):
kind create cluster --name argocd-mcp-test --image kindest/node:v1.37.0

# For cgroups v1 hosts (last supported release):
kind create cluster --name argocd-mcp-test --image kindest/node:v1.35.8

# Install ArgoCD
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Wait for ArgoCD to be ready
kubectl wait --for=condition=available --timeout=300s deployment/argocd-server -n argocd

# Get ArgoCD admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

# Port forward
kubectl port-forward svc/argocd-server -n argocd 8080:443

argocd-mcp-server/
├── src/argocd_mcp/
│   ├── server.py           # Entrypoint: FastMCP instance, lifespan, ServerContext, registration
│   ├── config.py           # Configuration management (pydantic-settings)
│   ├── tools/
│   │   ├── read.py         # Tier-1 read-only handlers
│   │   ├── write.py        # Tier-2 write handlers (require MCP_READ_ONLY=false)
│   │   ├── destructive.py  # Tier-3 destructive handlers (require confirmation)
│   │   ├── params.py       # Pydantic parameter models for every tool
│   │   └── _safety.py      # Shared destination-cluster guard
│   ├── resources/
│   │   └── applications.py # MCP resources: argocd://instances, argocd://security
│   └── utils/
│       ├── client.py       # ArgoCD API client with retry logic and secret masking
│       ├── safety.py       # Confirmation patterns, rate limiting
│       └── logging.py      # Structured logging, audit trail
├── tests/
│   ├── unit/               # Unit tests
│   └── integration/        # Integration tests (Kind cluster)
├── docs/
│   ├── TOOLS.md            # Detailed tool documentation
│   └── SECURITY.md         # Security model deep-dive
├── examples/               # Example configurations
└── Dockerfile              # Multi-stage container build