Aro MCP Server

ARO MCP服务器

用于Azure Red Hat OpenShift（ARO）集群管理的模型上下文协议（MCP）服务器。该服务器使GitHub Copilot等AI助手能够直接从VS Code查询、管理和排除ARO集群的故障。

演示

Your browser does not support the video tag. Download the demo video.

这是什么？

此MCP服务器将ARO集群操作作为AI代理可以调用的工具公开。当连接到VS Code Copilot（代理模式）时，您可以提出以下自然语言问题：

• *“在订阅xyz中列出我的ARO集群”*
• *“在资源组aro mcp centralus中获取aro mcp集群的详细信息”*
• *“我的ARO集群的配置状态如何？”*
• *“对eastus的ARO部署进行飞行前检查”*
• *“向我展示有关网络的ARO文档”*

Copilot将自动调用相应的ARO工具，从您的Azure订阅中检索实时数据。

可用工具

先决条件

• .NET 10 SDK 或以后
• Azure命令行界面 (az login 已认证）
• VS Code 和 扩展
• Azure OpenAI GPT-4o部署的资源（用于诊断/总结工具）
• Azure订阅 Microsoft.RedHatOpenShift 资源提供者已注册
• kubectl 的 或 oc命令行界面 用于集群操作
• 预建 azmcp.exe 二进制（参见 设置 在......下面

设置

1.克隆仓库

git clone https://github.com/microsoft/azure-aro-mcp-server.git
cd azure-aro-mcp-server

2.安装Azure MCP服务器二进制文件

下载或构建 azmcp 二进制并将其放入 ~/.aro-mcp/:

# Option A: Install from the official Azure MCP NuGet tool
dotnet tool install --global Azure.Mcp

# Option B: Use a pre-built binary
# Copy azmcp.exe to ~/.aro-mcp/ (Windows) or ~/.aro-mcp/ (Linux/macOS)
mkdir -p ~/.aro-mcp
cp /path/to/azmcp.exe ~/.aro-mcp/

3.使用Azure进行身份验证

在Windows上，Azure CLI在首次使用时可能会因AADSTS或令牌缓存错误而失败。运行这个 一次 要修复：

az account clear
az config set core.enable_broker_on_windows=false
az login
az account set --subscription 

注： 这 az account clear 和 az config set 步骤只需要一次。之后， az login 工作可靠。

4.配置VS代码MCP服务器

回购包括 .vscode/mcp.json 当您打开工作区时，它会自动注册服务器。无需手动设置。

将其添加到 另一个工作区 或 全球范围内，将此添加到您的VS代码中 settings.json:

{
  "mcp": {
    "servers": {
      "aro-mcp-server": {
        "type": "stdio",
        "command": "dotnet",
        "args": [
          "run", "--project",
          "/path/to/aro-mcp-server/tools/Azure.Mcp.Tools.Aro/src/Azure.Mcp.Tools.Aro.csproj",
          "--", "server", "start", "--transport", "stdio"
        ]
      }
    }
  }
}

5.向您的ARO集群进行身份验证

运行登录脚本——它会询问您想如何连接：

.\scripts\aro-login.ps1

ARO Cluster Login
  How would you like to connect?

  [S] Subscription lookup       — provide subscription ID, resource group, and cluster name
  [A] API Server direct login   — provide the ARO API server URL, username, and password

Choose login mode [S/A] (default: S):

选项A:直接登录API服务器（不需要Azure订阅）

如果您已经拥有ARO API服务器URL和凭证（例如。， kubeadmin 用户名/密码），选择 [A] 或使用 -Direct 标志：

# Interactive — prompts for API server URL, username, and password (password is hidden)
.\scripts\aro-login.ps1 -Direct

# With parameters (password is always prompted securely, never passed as argument)
.\scripts\aro-login.ps1 -Direct `
  -ApiServer "https://api.mycluster.eastus.aroapp.io:6443" `
  -Username "kubeadmin"

# With environment variables (password still prompted securely)
$env:ARO_API_SERVER = "https://api.mycluster.eastus.aroapp.io:6443"
$env:ARO_USERNAME = "kubeadmin"
.\scripts\aro-login.ps1 -Direct

安全： 密码总是使用以下方式提示 Read-Host -AsSecureString 并且永远不会显示、记录或存储在shell历史中。登录后立即从内存中清除。

要求： 只有 oc 需要CLI。没有Azure CLI，就没有Azure订阅。

选项B：订阅查找（自动凭证检索）

选择 [S] 或者直接提供参数。此模式使用Azure CLI自动检索kubeadmin凭据并将其交换为OAuth令牌，无需知道密码。

交互模式（提示输入所有值）：

.\scripts\aro-login.ps1

带参数：

.\scripts\aro-login.ps1 `
  -SubscriptionId "" `
  -ResourceGroup "" `
  -ClusterName ""

对于环境变量：

$env:AZURE_SUBSCRIPTION_ID = ""
$env:ARO_RESOURCE_GROUP = ""
$env:ARO_CLUSTER_NAME = ""
.\scripts\aro-login.ps1

Azure模式脚本的作用：

1. 验证Azure CLI登录（自动触发 az login 如果已过期）
2. 从Azure检索群集终结点
3. 获取kubeadmin凭据（从不显示）
4. 为OAuth令牌交换凭据（从不显示）
5. 配置 ~/.kube/config 使用令牌
6. 从内存中清除所有敏感数据

要求： Azure命令行界面(az), kubectl，一个可以访问ARO集群的Azure订阅。

Azure OpenAI配置（用于AI工具）

这 aro_cluster_diagnose 和 aro_cluster_summarize 工具需要Azure OpenAI。设置这些环境变量：

$env:AZURE_OPENAI_ENDPOINT = "https://your-resource.openai.azure.com/"
$env:AZURE_OPENAI_DEPLOYMENT = "gpt-4o"  # Your model deployment name

身份验证使用 DefaultAzureCredential （Azure CLI、托管身份等）。确保您的身份具有 认知服务OpenAI用户 Azure OpenAI资源上的角色。

登录后（任一模式）

kubectl get nodes
kubectl get clusteroperators
kubectl top nodes
oc get pods -A
oc get clusterversion

6.与Copilot配合使用

1. 打开VS Code并将Copilot Chat切换到 代理模式
2. 点击 工具图标 （扳手）确认列出了所有5个ARO工具(aro_cluster_get, aro_cluster_diagnose, aro_cluster_summarize, aro_cluster_preflight, aro_documentation_list)
3. 询问有关ARO集群的问题

客户问题诊断（不创建集群）

ARO MCP服务器最强大的用例之一是 诊断客户集群问题，而无需在您自己的订阅中创建任何ARO集群。您无需配置基础设施来重现问题，而是将诊断数据输入MCP服务器的AI工具，并立即获得专家级的根本原因分析。

为何这很重要

一步一步：诊断客户问题

步骤1--从客户处收集诊断数据

请客户（或通过跳转主机收集）在他们的ARO集群上运行这些命令。你做到了 不 需要访问客户的Azure订阅：

集群概述：

oc get nodes -o wide
oc adm top nodes
oc get clusterversion
oc get clusteroperators

节点健康状况（针对每个有问题的节点）：

oc describe node 
oc get node  -o jsonpath='{.spec.taints}'

Pod调度问题：

oc get pods -n  --field-selector status.phase!=Running
oc describe pod  -n 
oc get events -n  --sort-by='.lastTimestamp' | tail -30

存储问题：

oc get pvc -n 
oc describe pvc 
 -n 
oc get pv 
 -o yaml

节点磁盘压力（SSH/调试吊舱）：

oc debug node/
chroot /host
df -h /
du -sh /var/lib/containers/storage
podman images --format "{{.Repository}}:{{.Tag}} {{.Size}}"
crictl ps -a --state exited | wc -l

特定管道（Tekton）：

oc get pipelinerun -n 
oc get configmap feature-flags -n openshift-pipelines -o yaml
oc describe pipelinerun  -n 

步骤2——使用ARO MCP服务器打开VS代码

1. 使用打开VS代码 aro-mcp-server 工作区（或配置了MCP服务器的任何工作区）
2. 将Copilot聊天切换到 代理模式 （点击模式下拉菜单）
3. 验证MCP工具是否已加载--单击 工具图标 （扳手）并确认 aro_cluster_diagnose 已列出

步骤3——向人工智能提供诊断数据

将收集到的诊断输出与客户的问题描述一起粘贴到Copilot聊天中：

User: Customer's Tekton pipeline pods are stuck in Pending state on their ARO cluster.
      They have 4 worker nodes and 5 dedicated infra nodes.
      
      Here's the output from their cluster:
      
      [paste oc get nodes -o wide output]
      [paste oc adm top nodes output]
      [paste oc describe node output for problematic nodes]
      [paste oc get events output]
      [paste oc describe pvc output]
      [paste podman images output from the node]

步骤4——接收人工智能驱动的根本原因分析

MCP服务器通过以下方式将数据发送到Azure OpenAI（GPT-4o） aro_cluster_diagnose 工具和回报结构化分析：

Copilot → aro_cluster_diagnose:

  ROOT CAUSE:
  ✅ 3 of 4 worker nodes at 95-99% CPU requests — no scheduling headroom
  ✅ All pipeline builds forced onto the only node with available CPU (fqzxn)
  ✅ 12 stale pipeline images (4 GB each) accumulated → 141 GB → DiskPressure
  ✅ DiskPressure taint makes the node unschedulable → 0 nodes available

  IMMEDIATE FIX:
  • Clean stale pipeline images: podman rmi old int-server images
  • Delete completed PipelineRuns: oc delete pipelinerun 

  • Verify disk pressure taint clears automatically

  LONG-TERM RECOMMENDATIONS:
  • Add 2+ worker nodes via MachineSet (cluster is under-provisioned)
  • Configure Tekton pruner to auto-delete old PipelineRuns
  • Tune ImageGC thresholds (75% instead of 85%)
  • Switch pipelines to volumeClaimTemplate for ephemeral PVCs

步骤5——生成客户推荐

请Copilot将分析格式化为面向客户的建议：

User: Draft a customer recommendation document with the root cause,
      immediate actions, and long-term fixes with commands.

AI生成了一份专业报告，其中包括：

• 根本原因分析表
• 逐步修正命令
• 按优先级排序的建议（P0/P1/P2/P3）
• 容量规划指导

你可以诊断什么

真实世界的例子：ARO上的Tekton管道故障

这是一个完全通过ARO MCP服务器诊断的真实案例，无需创建任何集群：

总时间： 从第一次粘贴诊断到完成客户推荐文档大约需要30分钟。 已创建群集： 零。 Azure成本： 仅Azure OpenAI API调用（约0.05美元）。

体系结构——具有LLM和日志存储的数据流

flowchart LR
    subgraph Customer["Customer Environment"]
        CC["ARO Cluster"]
        JH["Jump Host / SSH"]
        CL["Diagnostic Logs\noc describe, events,\ntop nodes, pod logs,\npodman images"]
        CC --> JH
        JH --> CL
    end

    subgraph Engineer["Support Engineer (Local)"]
        VS["VS Code\n+ Copilot Agent Mode"]
        MCP["ARO MCP Server\n(aro_cluster_get,\naro_cluster_diagnose,\naro_cluster_summarize)"]
        LS["Log Storage\n(paste into chat /\nattach files /\nlocal workspace)"]
        VS |"Natural language\nquestions"| MCP
        LS -->|"Diagnostic\ndata"| VS
    end

    subgraph Azure["Azure Cloud"]
        AOAI["Azure OpenAI (GPT-4o)\n• Root cause analysis\n• Pattern recognition\n• Recommendation generation"]
        ARM["Azure Resource Manager\n• Cluster metadata\n• Configuration lookup\n• Subscription queries"]
        LA["Log Analytics (Optional)\n• Historical metrics\n• Diagnostic logs\n• KQL queries"]
    end

    CL -->|"1. Collect logs\n(no subscription needed)"| LS
    MCP -->|"2. aro_cluster_get\n(if subscription access exists)"| ARM
    MCP -->|"3. aro_cluster_diagnose\naro_cluster_summarize\n(sends logs + question)"| AOAI
    AOAI -->|"4. Root cause analysis\n& recommendations"| MCP
    ARM -->|"Cluster config\n& metadata"| MCP
    MCP -.->|"5. Optional: query\nhistorical logs"| LA

    style AOAI fill:#4a90d9,color:#fff
    style MCP fill:#2d8659,color:#fff
    style CC fill:#c0392b,color:#fff

每个组件的工作原理

关键见解： LLM（Azure OpenAI）接收集群诊断数据并返回专家分析。工程师不需要客户集群访问或Azure订阅，只需要客户或通过跳转主机收集的诊断输出（日志、描述、事件）。

队友入职（快速入门）

如果一个队友克隆了这个仓库，以下是让一切正常工作的最低清单：

一步一步

1. 安装。净10 SDK

   # Verify: dotnet --version should show 10.x

1. 安装Azure CLI并进行身份验证

   az account clear                              # one-time fix for Windows token cache
   az config set core.enable_broker_on_windows=false  # one-time fix for Windows
   az login
   az account set --subscription 

1. 构建MCP服务器插件

   cd azure-aro-mcp-server
   dotnet build tools/Azure.Mcp.Tools.Aro/src/Azure.Mcp.Tools.Aro.csproj

1. 安装Azure MCP运行时 --地点 azmcp.exe 在 ~/.aro-mcp/:

   # Option A: Install via .NET global tool
   dotnet tool install --global Azure.Mcp

   # Option B: Copy a pre-built binary
   New-Item -ItemType Directory -Force "$env:USERPROFILE\.aro-mcp"
   Copy-Item /path/to/azmcp.exe "$env:USERPROFILE\.aro-mcp\"

1. 在VS Code中打开工作区 — .vscode/mcp.json 自动注册服务器。无需手动配置。

1. 登录您的ARO集群

   .\scripts\aro-login.ps1

1. （可选）为AI工具配置Azure OpenAI --只需要 aro_cluster_diagnose 和 aro_cluster_summarize:

   $env:AZURE_OPENAI_ENDPOINT = "https://.openai.azure.com/"
   $env:AZURE_OPENAI_DEPLOYMENT = "gpt-4o"

你的身份也需要 认知服务OpenAI用户 Azure OpenAI资源上的角色。

什么能开箱即用，什么不能

用法示例

使用副驾驶（代理模式）

列出订阅中的所有集群：

User: List my ARO clusters

获取特定集群详细信息：

User: Get details of my-aro-cluster in resource group my-aro-rg

检查群集运行状况：

User: What is the provisioning state and worker count of my ARO cluster?

节点和操作员诊断（通过kubectl/oc）：

User: Check the ARO cluster node health and CPU utilization
User: Share the cluster operators status
User: Check DNS health on my ARO cluster

使用kubectl/oc命令行界面

运行后 .\scripts\aro-login.ps1 （或 .\scripts\aro-login.ps1 -Direct):

# Node status
kubectl get nodes -o wide

# CPU and memory utilization
kubectl top nodes

# Cluster operators
oc get clusteroperators

# DNS health
oc get dns.operator/default -o yaml
oc get pods -n openshift-dns

# Pod status across all namespaces
oc get pods -A --field-selector status.phase!=Running

# Cluster version
oc get clusterversion

直接oc登录（无需脚本）

安全： 切勿在命令行上传递密码（例如。， `oc login -p

`).命令行参数中的密码在进程列表、shell历史记录和终端日志中可见。

使用 oc login 相反，它将以交互方式安全地提示输入密码：

oc login https://api.mycluster.eastus.aroapp.io:6443 -u kubeadmin --insecure-skip-tls-verify
# Password: (enter securely at prompt — not displayed)

对于自动化/非交互式流，首选登录脚本，该脚本通过Azure CLI检索凭据，并将其交换为OAuth令牌，而不会暴露它们：

.\scripts\aro-login.ps1

该工具返回集群元数据，包括：

• 群集配置文件（域、版本、FIPS状态）
• API服务器配置文件（URL、IP、可见性）
• 控制台URL
• 网络配置文件（吊舱CIDR、服务CIDR、出站类型）
• 主配置文件（VM大小、子网、加密）
• 工作人员配置文件（计数、VM大小、磁盘大小、区域）
• 入口配置文件
• 配置状态
• 标签

故障排除

az login 由于AADSTS错误或令牌缓存问题而失败

如果您看到以下错误 Can't find token from MSAL cache, AADSTS50076，或 AADSTS5000224:

az account clear
az config set core.enable_broker_on_windows=false
az login

这将禁用Windows WAM代理并切换到基于浏览器的身份验证。

MCP服务器在VS代码中启动失败

1. 打开命令选项板(Ctrl+Shift+P) → MCP：列出服务器 → find aro-mcp-server → 重启
2. 确保您已通过身份验证： az account show
3. 验证 Microsoft.RedHatOpenShift 资源提供程序已注册：

   az provider show --namespace Microsoft.RedHatOpenShift --query "registrationState" -o tsv

1. 检查VS Code中的输出面板（从下拉列表中选择“MCP”）以获取错误详细信息

kubectl / oc 命令失败，出现身份验证错误

您的群集令牌可能已过期（令牌已过期24小时）。重新运行登录脚本：

.\scripts\aro-login.ps1

安装 oc 命令行界面

从下载 OpenShift镜像:

# Windows (PowerShell)
curl.exe -sLo "$env:TEMP\oc.zip" "https://mirror.openshift.com/pub/openshift-v4/clients/ocp/latest/openshift-client-windows.zip"
Expand-Archive "$env:TEMP\oc.zip" "$env:TEMP\oc-install" -Force
Copy-Item "$env:TEMP\oc-install\oc.exe" "$env:USERPROFILE\.aro-mcp\oc.exe"
# Add ~/.aro-mcp to your PATH

刀具参数

aro_cluster_get

ARO集群部署（二头肌）

这 aro-deploy/ 目录包含一个二头肌模板，用于创建ARO集群 托管身份 （不需要服务负责人）。这避免了企业租户中常见的凭据生命周期策略问题。

部署的先决条件

1. 注册ARO资源提供者 （每次订阅一次）：

   az provider register --namespace Microsoft.RedHatOpenShift --wait
   az provider show --namespace Microsoft.RedHatOpenShift --query "registrationState" -o tsv
   # Should output: Registered

1. 检查可用的ARO版本 在您的目标区域：

   az aro get-versions --location centralus -o table

1. 验证VM SKU可用性 （某些订阅限制了某些SKU）：

   az vm list-skus --location centralus --resource-type virtualMachines \
     --query "[?name=='Standard_D8s_v3'].restrictions" -o table

如果受到限制，请尝试其他区域或VM大小。

1. 获取ARO资源提供程序服务主体对象ID:

   az ad sp list --display-name "Azure Red Hat OpenShift RP" --query '[0].id' -o tsv

部署ARO集群

集群创建演示视频

https://github.com/microsoft/azure-aro-mcp-server/releases/download/demo-videos/aro_cluster_creation_compressed.mp4

# Set variables
LOCATION=centralus
RESOURCEGROUP=aro-rg
CLUSTER=my-aro-cluster
VERSION=4.18.34    # Use a version from az aro get-versions
ARO_RP_SP_OBJECT_ID=$(az ad sp list --display-name "Azure Red Hat OpenShift RP" --query '[0].id' -o tsv)

# Create resource group
az group create --name $RESOURCEGROUP --location $LOCATION

# Deploy ARO cluster (~35-45 minutes)
az deployment group create \
  --name aroDeployment \
  --resource-group $RESOURCEGROUP \
  --template-file aro-deploy/azuredeploy.bicep \
  --parameters location=$LOCATION \
  --parameters version=$VERSION \
  --parameters clusterName=$CLUSTER \
  --parameters rpObjectId=$ARO_RP_SP_OBJECT_ID

注： 部署大约需要35-45分钟。如果角色分配由于身份传播延迟而失败，只需重新运行部署即可——它是幂等的。

二头肌模板创建什么

默认配置：

• 主节点： 3x Standard_D8s_v3
• 工作节点： 3x Standard_D4s_v3 （128 GB磁盘）
• 网络： 吊舱CIDR 10.128.0.0/14，服务CIDR 172.30.0.0/16
• 可见性： 公共API服务器和入口

可定制参数

部署后

# Verify cluster is running
az aro show --name $CLUSTER --resource-group $RESOURCEGROUP \
  --query "{state:provisioningState, console:consoleProfile.url, api:apiserverProfile.url}" -o table

# Access the OpenShift console
az aro show --name $CLUSTER --resource-group $RESOURCEGROUP --query consoleProfile.url -o tsv

# Login securely using the login script (credentials never exposed)
# The script retrieves credentials via Azure CLI and exchanges them for an OAuth token
pwsh ./scripts/aro-login.ps1 -SubscriptionId "$SUBSCRIPTION_ID" -ResourceGroup "$RESOURCEGROUP" -ClusterName "$CLUSTER"

# Or login interactively (oc prompts for password securely)
API_URL=$(az aro show --name $CLUSTER --resource-group $RESOURCEGROUP --query apiserverProfile.url -o tsv)
oc login $API_URL -u kubeadmin --insecure-skip-tls-verify
# Password: (enter at secure prompt)

# IMPORTANT: Never use 'az aro list-credentials' output directly on the command line.
# Credentials in command-line arguments are visible in process lists and shell history.

清理

# Delete the ARO cluster and all resources
az aro delete --name $CLUSTER --resource-group $RESOURCEGROUP --yes
az group delete --name $RESOURCEGROUP --yes --no-wait

项目结构

aro-mcp-server/
├── .vscode/
│   └── mcp.json                          # VS Code MCP server auto-config
├── scripts/
│   └── aro-login.ps1                     # Secure ARO cluster authentication
├── aro-deploy/
│   └── azuredeploy.bicep                 # ARO cluster Bicep template (managed identity)
├── Directory.Build.props                 # Shared build settings (net10.0)
├── Directory.Packages.props              # Centralized NuGet package versions
├── aro-mcp-server.sln                    # Solution file
└── tools/
    └── Azure.Mcp.Tools.Aro/
        ├── src/
        │   ├── AroSetup.cs               # Tool area registration (IAreaSetup)
        │   ├── Commands/
        │   │   ├── AroJsonContext.cs      # AOT-compatible JSON serialization
        │   │   ├── BaseAroCommand.cs      # Base command class
        │   │   └── Cluster/
        │   │       └── ClusterGetCommand.cs  # aro_cluster_get implementation
        │   ├── Models/
        │   │   └── Cluster.cs            # ARO cluster model
        │   ├── Options/
        │   │   ├── AroOptionDefinitions.cs
        │   │   ├── BaseAroOptions.cs
        │   │   └── Cluster/
        │   │       └── ClusterGetOptions.cs
        │   └── Services/
        │       ├── AroService.cs         # Azure ARM client for ARO
        │       └── IAroService.cs
        └── tests/
            └── Azure.Mcp.Tools.Aro.UnitTests/
                └── Cluster/
                    └── ClusterGetCommandTests.cs

与您的团队分享

从源代码构建

该项目通过DLL引用核心MCP库 azmcp 安装目录(~/.aro-mcp/).要构建：

git clone https://github.com/microsoft/azure-aro-mcp-server.git
cd azure-aro-mcp-server
dotnet build

使用自定义构建 azmcp 位置：

dotnet build /p:AzmcpDir=/path/to/azmcp/directory

许可证

麻省理工学院