MCP Kubeadm Server

Kubeadm MCP服务器

一个模型上下文协议（MCP）服务器，用于使用Calico网络在Ubuntu系统上使用kubeadm管理Kubernetes集群。

🚀 快速开始AI集成

想在5分钟内开始使用人工智能驱动的Kubernetes管理吗？

👉 请参阅《入门指南》→

非常适合 VS代码与GitHub Copilot 和 光标 需要AI协助进行集群管理的用户！

🎯 单线设置

./start.sh

🎉 新：服务器现在提供 两个HTTP REST API 和 MCP协议!

✅ 快速测试 （无需设置）：

curl http://localhost:3000/                     # API discovery
curl http://localhost:3000/tools                # Available tools
curl -X POST http://localhost:3000/health/check # Health check

VS代码/光标：添加到 settings.json:

{
  "mcpServers": {
    "kubeadm-mcp": {
      "command": "node",
      "args": ["-e", "require('child_process').spawn('python3', ['-m', 'src.stdio_main'], {stdio: 'inherit'})"],
      "cwd": "/path/to/mcp-kubeadm"
    }
  }
}

测试：打开AI聊天并尝试： Help me set up a Kubernetes cluster

______________________________________________________________________

🌐 HTTP REST API

MCP服务器现在提供 完整HTTP REST API 与MCP协议一起实现最大可访问性：

📋 可用端点

🚀 快速示例

# API Discovery
curl http://localhost:3000/

# List Available Tools  
curl http://localhost:3000/tools

# Search Documentation
curl "http://localhost:3000/docs/search?q=calico&limit=5"

# Run Health Check
curl -X POST http://localhost:3000/health/check \
  -H "Content-Type: application/json" \
  -d '{"check_type": "basic", "include_ssh_tests": true}'

# Get Health Checklist
curl "http://localhost:3000/health/checklist?section=networking&format=commands"

# Validate Cluster
curl -X POST http://localhost:3000/cluster/validate \
  -H "Content-Type: application/json" \
  -d '{"auto_fix": false, "severity_threshold": "high"}'

# Troubleshoot Issues
curl -X POST http://localhost:3000/troubleshoot \
  -H "Content-Type: application/json" \
  -d '{"issue_type": "networking", "error_message": "pods pending"}'

# Execute MCP Tools Directly
curl -X POST http://localhost:3000/tools/search_docs \
  -H "Content-Type: application/json" \
  -d '{"query": "cluster init", "limit": 3}'

🔧 集成示例

Shell脚本：

#!/bin/bash
# Check cluster health in CI/CD
HEALTH=$(curl -s -X POST http://localhost:3000/health/check)
echo "Cluster Health: $HEALTH"

Python集成：

import requests

# Run health check
response = requests.post('http://localhost:3000/health/check', 
                        json={'check_type': 'full'})
health_data = response.json()
print(f"Health Status: {health_data['health_check']['total_categories']} checks")

监控/警报：

# Nagios/Zabbix health check
curl -f http://localhost:3000/health || exit 1

______________________________________________________________________

快速开始

先决条件

• Ubuntu 20.04+（推荐：Ubuntu 22.04 LTS）
• Docker已安装并正在运行
• Root或sudo访问权限
• 至少2个CPU内核，2GB RAM

1.Docker设置（推荐）

# Build the MCP server
docker build -t kubeadm-mcp-server .

# Run the MCP server
docker run -it --rm \
  --name kubeadm-mcp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.kube:/root/.kube \
  --network host \
  kubeadm-mcp-server

2.直接安装

# Install Python 3.8+ and pip
sudo apt update
sudo apt install -y python3 python3-pip python3-venv

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip3 install -r requirements.txt

# Start the MCP server
python3 src/main.py start

# Or use npm scripts (if you prefer)
npm run start

Kubernetes集群设置检查表

第一阶段：系统准备

• \[ \] 更新Ubuntu系统

  sudo apt update && sudo apt upgrade -y

• \[ \] 安装所需的软件包

  sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release

• \[ \] 禁用交换（Kubernetes需要）

  sudo swapoff -a
  sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

• \[ \] 配置内核模块

  cat  /dev/null

  sudo apt-get update
  sudo apt-get install -y containerd.io

• \[ \] 为Kubernetes配置containerd

  sudo mkdir -p /etc/containerd
  containerd config default | sudo tee /etc/containerd/config.toml
  sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml
  sudo systemctl restart containerd
  sudo systemctl enable containerd

第三阶段：Kubernetes安装

• \[ \] 添加Kubernetes APT存储库

  curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

  echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.29/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

• \[ \] 安装Kubernetes组件

  sudo apt-get update
  sudo apt-get install -y kubelet kubeadm kubectl
  sudo apt-mark hold kubelet kubeadm kubectl

阶段4：初始化Kubernetes集群

• \[ \] 使用自定义CIDR初始化集群

  sudo kubeadm init \
    --pod-network-cidr=172.100.10.0/24 \
    --service-cidr=10.96.0.0/12 \
    --apiserver-advertise-address=$(hostname -I | awk '{print $1}')

• \[ \] 为普通用户配置kubectl

  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

第5阶段：安装Calico CNI

• \[ \] 下载Calico清单

  curl https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/calico.yaml -O

• \[ \] 为Calico配置自定义CIDR（172.100.10.0/24）

  # Edit the calico.yaml file to match our CIDR
  sed -i 's|# - name: CALICO_IPV4POOL_CIDR|  - name: CALICO_IPV4POOL_CIDR|g' calico.yaml
  sed -i 's|#   value: "192.168.0.0/16"|    value: "172.100.10.0/24"|g' calico.yaml

• \[ \] 应用Calico网络

  kubectl apply -f calico.yaml

• \[ \] 验证Calico吊舱是否正在运行

  kubectl get pods -n kube-system -l k8s-app=calico-node
  kubectl get pods -n kube-system -l k8s-app=calico-kube-controllers

第6阶段：验证

• \[ \] 检查集群状态

  kubectl get nodes -o wide
  kubectl get pods -A

• \[ \] 验证网络配置

  # Check if CIDR is correctly configured
  kubectl cluster-info dump | grep -m 1 cluster-cidr
  kubectl get ippool -o yaml

• \[ \] 测试吊舱联网

  # Deploy test pod
  kubectl run test-pod --image=nginx --restart=Never
  kubectl get pod test-pod -o wide

  # Verify pod gets IP from 172.100.10.0/24 range
  kubectl exec test-pod -- ip addr show eth0

  # Cleanup
  kubectl delete pod test-pod

第7阶段：可选-删除Taint（单节点）

• \[ \] 删除单节点群集的主污染

  kubectl taint nodes --all node-role.kubernetes.io/control-plane-

网络配置详细信息

Calico与自定义CIDR（172.100.10.0/24）

• Pod网络CIDR: 172.100.10.0/24
• 服务网络CIDR: 10.96.0.0/12
• CNI插件：Calico v3.26.1
• 专利联盟: 172.100.10.0/24

验证命令

# Check IP pool configuration
kubectl get ippool default-ipv4-ippool -o yaml

# Verify Calico status
sudo calicoctl node status

# Check networking
kubectl get nodes -o wide
kubectl describe node $(hostname)

故障排除

常见问题

1. Pod卡在待定状态

   kubectl describe pod 

   kubectl logs -n kube-system -l k8s-app=calico-node

1. 节点未就绪状态

   kubectl describe node $(hostname)
   systemctl status kubelet
   journalctl -xeu kubelet

1. 网络问题

   # Check Calico status
   kubectl get pods -n kube-system | grep calico

   # Verify IP assignment
   kubectl get pods -o wide

🏥 健康检查和监测

MCP服务器包括全面的健康检查功能：

快速健康检查：

# Basic cluster health
curl -X POST http://localhost:3000/health/check

# Full health check with SSH tests
curl -X POST http://localhost:3000/health/check \
  -d '{"check_type": "full", "include_ssh_tests": true}'

健康检查类别：

• ✅ SSH连接 -测试对主节点/工作节点的访问权限
• ✅ 核心组件 -API服务器等、调度程序、控制器管理器
• ✅ 节点运行状况 -节点状态、资源、条件
• ✅ 网络 -Calico Pod、IP池、DNS解析
• ✅ 工作量 -Pod状态、部署、服务
• ✅ 安全 -RBAC、网络策略、PSP
• ✅ 演出 -资源使用情况、响应时间

获取具体清单：

# Get connectivity checklist  
curl "http://localhost:3000/health/checklist?section=connectivity"

# Get networking commands only
curl "http://localhost:3000/health/checklist?section=networking&format=commands"

使用自动修复进行验证：

# Validate and get recommendations
curl -X POST http://localhost:3000/cluster/validate \
  -d '{"severity_threshold": "medium", "auto_fix": false}'

🔧 自动故障排除

常见问题解决：

# Network troubleshooting
curl -X POST http://localhost:3000/troubleshoot \
  -d '{"issue_type": "networking", "error_message": "CoreDNS pods pending"}'

# Node issues
curl -X POST http://localhost:3000/troubleshoot \
  -d '{"issue_type": "node_not_ready", "error_message": "kubelet stopped posting"}'

# Join failures
curl -X POST http://localhost:3000/troubleshoot \
  -d '{"issue_type": "join_failure", "error_message": "connection refused"}'

重置群集（如果需要）

sudo kubeadm reset -f
sudo rm -rf /etc/kubernetes/
sudo rm -rf ~/.kube/
sudo rm -rf /var/lib/etcd/

测试覆盖

我们的MCP Kubeadm服务器经过全面测试 100%通过率（56/56次测试）:

✅ 单元测试（38/38通过）

• 数据库管理器：文档存储、搜索、配置管理
• 文档获取器：内容解析、命令提取、错误处理
• MCP服务器：工具调用、错误处理、服务器操作
• KubeadmManager：集群运营和管理

✅ 集成测试（12/12通过）

• 数据库+Fetcher集成：端到端文档工作流
• MCP服务器+数据库集成：具有真实数据库操作的工具调用
• MCP服务器+Kubeadm集成：完成群集管理工作流
• 完整的工作流集成：完整用户场景和错误恢复

✅ 性能测试（6/6通过）

• 数据库性能：329个文档/秒插入，589次搜索/秒
• MCP服务器性能：平均响应时间2ms，699个呼叫/秒并发
• 内存效率：每份文档0.004MB，未检测到内存泄漏

运行测试

# Run all tests (56 total)
pytest tests/ -v

# Run specific test categories
pytest tests/test_mcp_server.py -v      # Unit tests (38)
pytest tests/test_integration.py -v     # Integration tests (12)
pytest tests/test_performance.py -v     # Performance tests (6)

# Run with coverage
pytest tests/ --cov=src --cov-report=html

性能基准

• 搜索响应时间：平均29ms（目标：\<100ms）✅ 快3.4倍
• 工具调用响应：平均2ms（目标：\<500ms）✅ 速度提高250倍
• 并发处理：699次呼叫/秒✅ 70倍目标性能
• 内存使用：每份文件0.004MB✅ 极其有效

看 测试报告.md 进行详细的性能分析。

🛠️ MCP服务器功能

🎯 核心能力

集群管理：

• ✅ 交互式集群设置 有指导的步骤
• ✅ 健康监测 进行全面检查
• ✅ 故障排除帮助 进行根本原因分析
• ✅ 配置验证 最佳实践
• ✅ 网络故障排除 （加州特定）

文档与学习：

• ✅ 21+策划文档 来自kubernetes.io
• ✅ 语义搜索 在所有文档中
• ✅ 命令帮助 以现实世界为例
• ✅ 最佳实践 适用于Ubuntu+Calico部署

集成与自动化：

• ✅ HTTP REST API 用于CI/CD集成
• ✅ MCP协议 用于AI编辑器集成
• ✅ 健康检查端点 用于监控
• ✅ API故障排除 用于自动分辨率

🔧 可用工具

🎯 使用示例

AI编辑器集成 （光标/VCode）：

💬 "Help me troubleshoot why my CoreDNS pods are stuck"
💬 "Generate a cluster config for production with Calico"
💬 "Run a full health check on my cluster"

HTTP API集成:

# CI/CD Pipeline Health Check
curl -X POST http://localhost:3000/health/check | jq '.health_check.total_categories'

# Automated Troubleshooting
curl -X POST http://localhost:3000/troubleshoot \
  -d '{"issue_type": "pods_pending"}' | jq '.guidance'

可用资源：

• 📚 kubeadm://docs/ -完整文档数据库
• 🏥 kubeadm://health/checklist -健康检查程序
• 📊 kubeadm://health/results -最新健康检查结果
• 📖 kubeadm://lessons/ -业务经验教训

🚀 非常适合

• DevOps工程师：自动化集群运行状况监测
• 平台团队：标准化故障排除程序
• 人工智能开发：上下文感知集群管理
• CI/CD管道：自动验证和健康检查
• 学习：使用最佳实践指导Kubernetes设置

📚 额外资源

• 课程_学习.md -操作指南和故障排除方法
• 健康检查.md -全面的健康检查程序和验证
• GETTING_STARTED.md -详细的设置指南和分步说明

支持和文档

• Kubernetes文档: https://kubernetes.io/docs/
• Calico文件: https://docs.projectcalico.org/
• Ubuntu Kubernetes指南: https://ubuntu.com/kubernetes
• MCP协议: https://modelcontextprotocol.org/

______________________________________________________________________

🎯 版本中的新功能

✨ 新增主要功能：

• 🌐 完整HTTP REST API -用于集成的直接端点访问
• 🏥 全面健康检查 -7类集群验证
• 🔧 自动故障排除 -上下文感知问题解决
• 📊 健康监测 -实时集群状态和验证
• 🚀 增强的性能 -响应时间快250倍
• 📖 经验教训整合 -内置操作指南
• 🎯 双协议支持 -HTTP API和MCP协议

🔥 非常适合：

• 生产集群 -可靠的健康监测和故障排除
• CI/CD集成 -自动健康检查和验证
• 人工智能驱动的DevOps -上下文感知集群管理
• 学习与发展 -使用最佳实践指导设置
• 企业使用 -全面的文档和支持