平台MCP服务器
通过以下方式将AKS操作数据暴露给AI助手 模型上下文协议.
Platform MCP Server为平台工程师提供了跨多租户AKS车队进行监控、诊断和升级跟踪的自然语言访问权限，而无需离开他们的人工智能助手。
特性
- 节点池压力 --CPU/内存利用率、挂起的Pod和每个池的自动缩放器净空
- Pod健康诊断 --通过OOMKill检测按故障类别（调度、运行时、注册表、配置）分组的失败和挂起的Pod
- Kubernetes升级状态 --控制平面和节点池版本、可用升级、弃用版本警告
- 升级进度跟踪 --每个节点状态（升级/升级/封锁/停滞）、经过的时间、估计剩余时间、异常标志
- 升级持续时间指标 --Azure活动日志中P90基线的当前和历史计时
- PDB升级风险 --对可能堵塞节点排水的PodDisruption预算进行飞行前和实时检测
- 全车队查询 --通行证
cluster="all"在所有6个集群中并行展开 - LLM安全输出 --结构化JSON，无堆栈跟踪，敏感数据自动清除
建筑
┌─────────────────────────────────────────────────────────┐
│ AI Assistant (Claude, Cursor, etc.) │
│ ▲ │
│ │ stdio (MCP protocol) │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Platform MCP Server │ │
│ │ │ │
│ │ server.py ─── FastMCP tool registration │ │
│ │ │ │ │
│ │ tools/ ─── One tool per module │ │
│ │ │ (node_pools, pod_health, ...) │ │
│ │ │ │ │
│ │ clients/ ─── One client per API surface │ │
│ │ │ (k8s_core, k8s_metrics, azure) │ │
│ │ │ │ │
│ │ models.py ─── Pydantic v2 I/O schemas │ │
│ │ config.py ─── Cluster map & thresholds │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │ │
│ Kubernetes APIs Azure ARM APIs │
│ (Core, Metrics, Policy, (AKS, Activity Log) │
│ Events) │
└─────────────────────────────────────────────────────────┘关键设计决策：
- 只读 --无写入操作；可以安全地接触人工智能助手
- stdio传输 --无网络监听；作为每个工程师的本地子流程运行
- 每个模块一个工具 --每个工具都是可独立测试和部署的
- 结构化错误 --Pydantic
ToolError模型用可操作的消息替换堆栈跟踪 - 优雅降级 --当单个数据源失败时返回部分结果
先决条件
- Python 3.14+
- 紫外线 包管理器
- Azure CLI已通过身份验证(
az login) - Kubeconfig为您的AKS集群提供上下文(
az aks get-credentials)
入门
1.克隆并安装
git clone https://github.com/dudick123/platform-mcp-server.git
cd platform-mcp-server
uv sync2.配置集群
复制示例集群配置并填写您的真实Azure订阅ID：
cp clusters.example.yaml clusters.yaml
# Edit clusters.yaml and replace placeholders with real UUIDs这 clusters.yaml 文件被git忽略，因此凭据永远不会被提交。您可以用以下命令覆盖文件路径 PLATFORM_MCP_CLUSTERS 环境变量。
3.身份验证
az login
az aks get-credentials --resource-group rg-dev-eastus --name aks-dev-eastus
# Repeat for each cluster4.运行服务器
python -m platform_mcp_server.server服务器使用MCP协议从stdin读取并写入stdout。日志将转到stderr。
客户端集成
克劳德桌面版
添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：
{
"mcpServers": {
"platform-mcp-server": {
"command": "uv",
"args": [
"run", "--directory", "/path/to/platform-mcp-server",
"python", "-m", "platform_mcp_server.server"
]
}
}
}克劳德代码
添加到您的项目 .mcp.json:
{
"mcpServers": {
"platform-mcp-server": {
"command": "uv",
"args": [
"run", "--directory", "/path/to/platform-mcp-server",
"python", "-m", "platform_mcp_server.server"
]
}
}
}VS代码/光标
通过编辑器中的MCP服务器设置进行配置，指向相同的 uv run 命令。
工具参考
check_node_pool_pressure
检查群集中节点池的CPU和内存压力。
cluster: "prod-eastus" # or "all" for fleet-wide返回每个池的CPU请求比率、内存请求比率、挂起的pod计数、就绪/最大节点计数和压力水平(ok, warning, critical).
get_pod_health
获取失败和挂起的Pod的诊断。
cluster: "prod-eastus"
namespace: "default" # optional — omit for all namespaces
status_filter: "all" # "pending", "failed", or "all"返回按故障类别分组的Pod，其中包含重启计数、事件上下文和OOMKill检测。上限为50个豆荚。
get_kubernetes_upgrade_status
获取Kubernetes版本并升级可用性。
cluster: "all" # fleet-wide version table返回控制平面版本、每个池的版本、可用升级、支持状态和正在进行的升级检测。
get_upgrade_progress
在升级过程中跟踪每个节点的进度。
cluster: "prod-eastus"
node_pool: "system" # optional — omit for all pools返回每个节点的状态(upgraded, upgrading, cordoned, pdb_blocked, pending, stalled)、经过/估计时间和异常标志。
get_upgrade_duration_metrics
获取当前和历史升级时间。
cluster: "prod-eastus"
node_pool: "system"
history_count: 5 # 1–50, number of historical records返回当前运行时间、来自事件API的每个节点计时以及来自活动日志的平均/P90/min/max的历史持续时间。
check_pdb_upgrade_risk
检查可能阻止升级的播客中断预算风险。
cluster: "prod-eastus"
node_pool: "system" # optional — omit for cluster-wide
mode: "preflight" # "preflight" or "live"- 预检 --在开始升级之前，评估所有PDB的排水堵塞风险
- 生活 --识别当前阻止在封锁节点上驱逐的PDB
使用示例
连接到AI助手后，使用自然语言进行交互：
“检查所有生产集群的节点池压力” 助理打来电话 check_node_pool_pressure(cluster="all") 并返回每个池的CPU/内存利用率摘要，突出显示处于警告或关键级别的任何池。“staging eastus的默认命名空间中是否有任何失败的Pod？” 助理打来电话 get_pod_health(cluster="staging-eastus", namespace="default") 并按故障类别对结果进行分组——调度问题、图像拉取错误、OOMKill等。“舰队中运行着哪些Kubernetes版本？” 助理打来电话 get_kubernetes_upgrade_status(cluster="all") 并呈现了一个版本表，显示了每个集群的控制平面版本、节点池版本和可用升级。“prod-eastus升级似乎停滞不前。发生了什么事？” 助理打来电话get_upgrade_progress(cluster="prod-eastus")要显示每个节点的状态，则check_pdb_upgrade_risk(cluster="prod-eastus", mode="live")以识别任何堵塞排水管的PDB。
“prod-eastus上的系统池最近5次升级花了多长时间？” 助理打来电话 get_upgrade_duration_metrics(cluster="prod-eastus", node_pool="system", history_count=5) 并返回具有P90基线的定时摘要。配置
阈值可以通过环境变量进行配置：
| 变量 | 默认值 | 描述 |
|---|---|---|
PRESSURE_CPU_WARNING | 75 | 触发警告的CPU请求比率（%） |
PRESSURE_CPU_CRITICAL | 90 | 触发临界的CPU请求比率（%） |
PRESSURE_MEMORY_WARNING | 80 | 触发警告的内存请求比率（%） |
PRESSURE_MEMORY_CRITICAL | 95 | 触发临界的内存请求比率（%） |
PRESSURE_PENDING_PODS_WARNING | 1 | 等待吊舱计数以触发警告 |
PRESSURE_PENDING_PODS_CRITICAL | 10 | 等待吊舱计数以触发临界值 |
UPGRADE_ANOMALY_MINUTES | 60 | 升级被标记为停滞前几分钟 |
PLATFORM_MCP_CLUSTERS | clusters.yaml | 集群配置YAML文件的路径 |
项目结构
clusters.example.yaml # Template cluster configuration (copy to clusters.yaml)
src/platform_mcp_server/
├── server.py # MCP entry point and tool registration
├── config.py # Cluster YAML loader and thresholds
├── models.py # Pydantic v2 I/O schemas
├── validation.py # Input validation (namespace, node pool, mode)
├── utils.py # Shared utilities (timestamp parsing)
├── tools/
│ ├── node_pools.py # check_node_pool_pressure
│ ├── pod_health.py # get_pod_health
│ ├── k8s_upgrades.py # get_kubernetes_upgrade_status
│ ├── upgrade_progress.py# get_upgrade_progress
│ ├── upgrade_metrics.py # get_upgrade_duration_metrics
│ ├── pdb_check.py # check_pdb_upgrade_risk
│ └── pod_classification.py # Shared failure categorization
└── clients/
├── k8s_core.py # Nodes, pods, namespaces (Core v1)
├── k8s_metrics.py # CPU/memory usage (metrics.k8s.io)
├── k8s_events.py # Upgrade and pod events (Core v1)
├── k8s_policy.py # PodDisruptionBudgets (policy/v1)
└── azure_aks.py # Cluster info, versions, activity log发展
设置
uv sync
uv run pre-commit install运行检查
uv run ruff check . # Lint
uv run ruff format --check . # Format check
uv run mypy src/ # Type check (strict mode)
uv run bandit -c pyproject.toml -r src/ # Security scan
uv run pytest --cov --cov-report=term # Tests with coverage (90% minimum)CI管道
GitHub操作工作流(.github/workflows/ci.yml)每次推都会跑 main 以及拉取请求。它运行两个并行作业：
- 棉绒 --ruff检查，ruff格式，mypy严格，土匪安全扫描
- 测试 --具有覆盖强制的pytest（≥90%）
Dev容器
VS Code包含一个开发容器配置。打开仓库并选择 “在容器中重新打开” 用于使用Python、uv、Azure CLI和kubectl的预配置环境。你的 ~/.azure 和 ~/.kube 目录是以只读方式挂载的。
\[！注意\] 服务器使用 仅限stdio传输 --它作为每个工程师的本地子进程运行，不公开网络侦听器。所有操作都是只读的。