# Azure Platform Engineering MCP Server

A Model Context Protocol (MCP) server connected to **real Azure infrastructure**. Deploys a live AKS cluster and provides AI agents with real-time access to cluster health, Azure resources, policy validation, and Terraform analysis.

No simulated data. Every API call hits live Azure services.

---

## What This Does

This MCP server gives AI agents (Claude Code, GitHub Copilot, etc.) structured access to a real Azure platform:

| Tool | Data Source | What It Returns |
|------|-------------|-----------------|
| `check_cluster_health` | Kubernetes API (live AKS) | Real node status, pod health, events, recommendations |
| `validate_manifest` | PyYAML parser | Policy compliance for real YAML manifests |
| `analyze_terraform` | HCL analysis | Quality score for Terraform modules |
| `query_azure_resources` | Azure Resource Manager API | Real resource groups, AKS clusters, VMs |

---

## Architecture

![Architecture Overview](diagrams/01-architecture-overview.png)

### How It Works

![MCP Protocol Flow](diagrams/02-mcp-protocol-flow.png)

### Deployment Pipeline

![Deployment Pipeline](diagrams/03-deployment-pipeline.png)

---

## Live Proof

This was deployed and tested against a real AKS cluster on Azure for Students.

### kubectl get nodes
![kubectl get nodes](diagrams/kubectl-get-nodes.png)

### kubectl get pods (with real CrashLoopBackOff)
![kubectl get pods](diagrams/kubectl-get-pods.png)

### MCP Server Test Output (LIVE)
![Live test output](diagrams/live-test-output.png)

### Azure Portal
![Azure Portal](diagrams/azure-portal-aks.png)

---

## Infrastructure

Deployed via Terraform in `terraform/main.tf`:

| Resource | Details |
|----------|---------|
| Resource Group | `mcp-demo-rg` (Sweden Central) |
| AKS Cluster | `aks-platform-demo` — Kubernetes 1.32 |
| Node Pool | 1x Standard_D2as_v4 (cost-optimised) |
| Network | Azure CNI + Calico network policy |
| Monitoring | Log Analytics workspace + OMS agent |
| Workloads | 3 namespaces: product-api, product-web, platform-monitoring |

The `platform-monitoring` namespace includes an intentionally failing pod to demonstrate how the health check tool detects and reports real CrashLoopBackOff incidents.

---

## Setup

### Prerequisites

- Azure subscription (Azure for Students works)
- Azure CLI (`az`)
- Terraform
- kubectl
- Python 3.10+

### Deploy

```bash
# 1. Clone
git clone https://github.com/sat0ps/mcp-server-azure-platform.git
cd mcp-server-azure-platform

# 2. Login to Azure
az login

# 3. Deploy infrastructure
cd terraform
terraform init
terraform plan
terraform apply

# 4. Configure kubectl
az aks get-credentials --resource-group mcp-demo-rg --name aks-platform-demo

# 5. Deploy sample workloads
kubectl apply -f workloads.yaml

# 6. Install dependencies
cd ..
pip install -r requirements.txt

# 7. Set subscription ID
export AZURE_SUBSCRIPTION_ID=$(az account show --query id -o tsv)

# 8. Test
python test_tools.py
```

### Tear Down (stop costs)

```bash
cd terraform
terraform destroy
```

---

## Live Test Output

```
Platform Engineering MCP Server — Live Test Suite
============================================================
Testing against REAL Azure infrastructure

TEST: Initialize
  Server: azure-platform-engineering-mcp v1.0.0
  PASS

TEST: Check Cluster Health (LIVE)
  Source: LIVE — Kubernetes API
  Health Score: 100 (healthy)
  Nodes: 1/1 ready
  Pods: 25 running, 0 pending, 0 failed
  Problem pods:
    - platform-monitoring/failing-service: 6 restarts (CrashLoopBackOff)
  PASS

TEST: Query Azure Resources (LIVE)
  Source: LIVE — Azure Resource Manager API
  AKS Clusters found: 1
    - aks-platform-demo (swedencentral) — K8s 1.32 — Succeeded
      Pool: system — Standard_D2as_v4 x1
  PASS

ALL TESTS PASSED (Live Azure)
```

---

## Diagrams

| Diagram | What It Shows |
|---------|---------------|
| [Architecture Overview](diagrams/01-architecture-overview.png) | Full system: agent → MCP → live tools → real Azure |
| [MCP Protocol Flow](diagrams/02-mcp-protocol-flow.png) | Real request flow with CrashLoopBackOff detection |
| [Deployment Pipeline](diagrams/03-deployment-pipeline.png) | terraform apply → kubectl → test → destroy |
| [Incident Detection](diagrams/04-incident-detection.png) | How MCP found the failing-service pod |
| [Policy Validation](diagrams/05-policy-validation.png) | YAML validation gate with real PyYAML parsing |
| [Agent Configuration](diagrams/06-agent-config.png) | How agents.md + skills + instructions work together |
| [Terraform PR Review](diagrams/07-terraform-review.png) | AI-driven PR review with quality scoring |

---

## Project Structure

```
├── mcp_server.py              # MCP server (JSON-RPC 2.0 over stdio)
├── tools/
│   ├── kubernetes_live.py     # Real K8s API health checks
│   ├── compliance_live.py     # Real YAML policy validation
│   ├── terraform_live.py      # Terraform HCL analysis
│   ├── azure_resources.py     # Real Azure Resource Manager queries
│   └── azure_metrics.py       # Azure Monitor metrics (SDK v2 WIP)
├── terraform/
│   ├── main.tf                # AKS + monitoring infrastructure
│   └── workloads.yaml         # Sample K8s deployments
├── .claude/
│   ├── agents.md              # Agent behaviour configuration
│   └── mcp.json               # Claude Code MCP config
├── skills/
│   └── SKILL.md               # Repeatable agent procedures
├── instructions/
│   ├── terraform-standards.md # Terraform quality standards
│   └── kubernetes-standards.md# K8s deployment requirements
├── scripts/
│   └── setup.sh               # Automated deployment script
├── diagrams/                  # Architecture diagrams + live screenshots
├── requirements.txt           # Python dependencies
└── test_tools.py              # Live test suite
```

---

## Authentication

Uses `DefaultAzureCredential` — works with `az login`, managed identity, and service principals. No credentials stored in the repo.

---

## Related

- [Microsoft Azure MCP Server](https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/) — Microsoft's official generic Azure MCP server
- [Model Context Protocol](https://modelcontextprotocol.io/) — MCP specification
- [platform-engineering-mcp-server](https://github.com/sat0ps/platform-engineering-mcp-server) — Simulated version (design-first approach)

---

## License

MIT