Platform MCP Server (Dudick123)

平台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 sync

2.配置集群

复制示例集群配置并填写您的真实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 cluster

4.运行服务器

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基线的定时摘要。

配置

阈值可以通过环境变量进行配置：

项目结构

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传输 --它作为每个工程师的本地子进程运行，不公开网络侦听器。所有操作都是只读的。