内容
# kubevirt-mcp-server
一个用于 KubeVirt 的简单模型上下文协议服务器。
## 架构
该项目被组织成模块化包：
- `main.go` - MCP 服务器设置和注册
- `pkg/client/` - 共享 KubeVirt 客户端实用程序
- `pkg/tools/` - 用于 VM 操作的 MCP 工具处理程序
- `pkg/resources/` - 用于结构化数据访问的 MCP 资源处理程序
- `scripts/kubevirtci.sh` - 用于管理本地 kubevirtci 开发环境的脚本
- `scripts/sync.sh` - 用于在本地构建和运行具有 kubevirtci 访问权限的 MCP 服务器的脚本
- `Makefile` - 构建自动化和开发任务
## 功能
### MCP Tools
- `list_vms` - 列出命名空间中的虚拟机名称
- `start_vm` - 启动虚拟机
- `stop_vm` - 停止虚拟机
- `restart_vm` - 重启虚拟机（处理运行和停止的虚拟机）
- `pause_vm` - 暂停虚拟机
- `unpause_vm` - 取消暂停虚拟机
- `create_vm` - 创建具有指定容器磁盘的虚拟机（支持操作系统名称查找），可选的 instancetype 和 preference
- `delete_vm` - 删除虚拟机
- `patch_vm` - 应用 JSON 合并补丁以修改 VM 配置
- `list_instancetypes` - 列出可用的实例类型
- `get_instancetype` - 获取有关特定实例类型的详细信息
- `get_preference` - 获取有关特定 preference 的详细信息
- `get_vm_instancetype` - 获取 VM 的实例类型
- `get_vm_status` - 获取全面的 VM 状态信息
- `get_vm_conditions` - 获取详细的 VM condition 信息
- `get_vm_phase` - 获取当前 VM 阶段和基本状态
- `get_vm_disks` - 检索附加到虚拟机的磁盘列表
### MCP Prompts
- `describe_vm` - 提供全面的 VM 描述，包括配置、状态和操作详细信息
- `troubleshoot_vm` - 诊断和分析潜在的 VM 问题，并提供可操作的建议
- `health_check_vm` - 执行快速 VM 健康检查并报告问题
### MCP Resources
- `kubevirt://{namespace}/vms` - 具有摘要信息的 VM 的 JSON 列表
- `kubevirt://{namespace}/vm/{name}` - 完整的 VM 规范
- `kubevirt://{namespace}/vm/{name}/status` - VM 状态和阶段信息
- `kubevirt://{namespace}/vm/{name}/console` - VM 控制台连接详细信息
- `kubevirt://{namespace}/vmis` - 具有运行时信息的 VMI 的 JSON 列表
- `kubevirt://{namespace}/vmi/{name}` - 完整的 VMI 规范
- `kubevirt://{namespace}/vmi/{name}/guestosinfo` - VMI 客户操作系统信息
- `kubevirt://{namespace}/vmi/{name}/filesystems` - VMI 文件系统信息
- `kubevirt://{namespace}/vmi/{name}/userlist` - VMI 用户列表信息
- `kubevirt://{namespace}/datavolumes` - 具有源和存储信息的 DataVolume 的 JSON 列表
- `kubevirt://{namespace}/datavolume/{name}` - 完整的 DataVolume 规范
- `kubevirt://{namespace}/instancetypes` - 命名空间的实例类型
- `kubevirt://{namespace}/preferences` - 命名空间的 VM preferences
- `kubevirt://cluster/instancetypes` - 集群范围的实例类型
- `kubevirt://cluster/preferences` - 集群范围的 VM preferences
- `kubevirt://cluster/instancetype/{name}` - 特定集群实例类型
- `kubevirt://cluster/preference/{name}` - 特定集群 preference
## 构建
```bash
# Using Makefile (recommended)
make build
# Or directly with go
go build -o kubevirt-mcp-server .
```
## 开发
### Available Make Targets
- `make build` - 构建二进制文件（默认）
- `make clean` - 清理构建工件
- `make test` - 使用 Ginkgo 框架运行测试
- `make coverage` - 生成测试覆盖率报告
- `make fmt` - 格式化 Go 代码
- `make vet` - 运行 go vet
- `make lint` - 运行 golangci-lint
- `make deps` - 下载和整理依赖项
- `make run` - 构建并运行服务器
- `make check` - 运行 fmt、vet、lint 和 test
- `make cluster-up` - 启动 kubevirtci 集群进行测试
- `make cluster-down` - 停止 kubevirtci 集群
- `make cluster-sync` - 在本地构建和运行具有 kubevirtci 访问权限的 MCP 服务器
- `make test-functional` - 针对 MCP 服务器运行功能测试
- `make help` - 显示帮助消息
### 测试
该项目使用 [Ginkgo](https://github.com/onsi/ginkgo) 测试框架和 [Gomega](https://github.com/onsi/gomega) 断言：
```bash
# Run unit tests
make test
# Generate test coverage report
make coverage
# Run functional tests against MCP server
make test-functional
# Run linter
make lint
# Run all quality checks
make check
```
### 本地开发环境
对于使用真实 KubeVirt 集群进行功能测试，请使用 kubevirtci 集成：
```bash
# Start a local kubevirtci cluster with KubeVirt
make cluster-up
# Stop the cluster when done
make cluster-down
# Build and run MCP server locally with cluster access
make cluster-sync
```
kubevirtci 集成包括：
**`scripts/kubevirtci.sh`** 处理：
- 下载和设置 kubevirtci
- 启动具有 KubeVirt 和 CDI 的本地 Kubernetes 集群
- 配置测试环境
- 提供对 kubectl、kubeconfig 和注册表的访问
**`scripts/sync.sh`** 处理：
- 构建 MCP 服务器二进制文件
- 设置正确的 KUBECONFIG 环境以进行 kubevirtci 访问
- 提供本地 MCP 服务器执行的说明
### 测试结构
该项目包括全面的测试覆盖率：
- **单元测试** - 隔离测试各个组件
- `pkg/client/client_test.go` - KubeVirt 客户端创建测试
- `pkg/tools/tools_test.go` - MCP 工具处理程序参数验证
- `pkg/resources/resources_test.go` - MCP 资源处理程序 URI 解析
- **功能测试** - 测试完整的 MCP 服务器功能
- `tests/functional/functional_suite_test.go` - 测试套件设置和 KubeVirt 集群验证
- `tests/functional/mcp_server_stdio_test.go` - 完整的 MCP 服务器 API 覆盖率：
- MCP 服务器初始化和 JSON-RPC 通信
- 所有 MCP 工具：list_vms、start_vm、stop_vm、restart_vm、create_vm、list_instancetypes、get_vm_instancetype、get_vm_disks
- 所有 MCP 资源：kubevirt://namespace/vms、vm/name、vmis、vmi/name 端点
- 无效工具、缺少参数、无效 URI 和不存在的 VM 的错误处理
## 与 Claude CLI 一起使用
此 MCP 服务器与 Claude CLI (Claude Code) 无缝集成，以在您的开发工作流程中直接提供 KubeVirt 管理功能。
### 配置
#### 方法 1：项目特定配置
在您的项目目录中创建一个 `.clauderc` 文件：
```json
{
"mcp": {
"servers": {
"kubevirt": {
"command": "/path/to/kubevirt-mcp-server",
"env": {
"KUBECONFIG": "/path/to/your/kubeconfig"
}
}
}
}
}
```
#### 方法 2：全局配置
在您的全局 Claude 设置中进行配置：
```bash
# Create/edit global Claude config
mkdir -p ~/.config/claude
cat > ~/.config/claude/config.json << 'EOF'
{
"mcp": {
"servers": {
"kubevirt": {
"command": "/path/to/kubevirt-mcp-server",
"env": {
"KUBECONFIG": "/path/to/your/kubeconfig"
}
}
}
}
}
EOF
```
#### 方法 3：环境变量
设置环境变量以进行动态配置：
```bash
export KUBEVIRT_MCP_SERVER="/path/to/kubevirt-mcp-server"
export KUBECONFIG="/path/to/your/kubeconfig"
# Use in Claude config
{
"mcp": {
"servers": {
"kubevirt": {
"command": "$KUBEVIRT_MCP_SERVER",
"env": {
"KUBECONFIG": "$KUBECONFIG"
}
}
}
}
}
```
### 设置步骤
1. **构建 MCP 服务器**
```bash
git clone <your-repo>
cd kubevirt-mcp-server
make build
# Note the path to the binary
echo "Binary location: $(pwd)/kubevirt-mcp-server"
```
2. **验证 KubeVirt 访问**
```bash
# Test your kubeconfig works
kubectl get vms --all-namespaces
# Test the MCP server directly
export KUBECONFIG=/path/to/your/kubeconfig
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | ./kubevirt-mcp-server
```
3. **配置 Claude CLI**
使用上述配置方法之一，确保：
- `command` 路径指向您构建的二进制文件
- `KUBECONFIG` 环境变量指向您的集群配置
- kubeconfig 具有 VM 操作的适当权限
4. **测试集成**
```bash
# Start Claude CLI and test MCP server connectivity
claude --list-mcp-servers
# Should show "kubevirt" server as available
```
### 用法示例
配置完成后，您可以使用 Claude CLI 和自然语言来管理您的 VM：
#### VM 管理
```bash
# List and manage VMs
claude "List all VMs in the production namespace"
claude "Start the web-server VM in default namespace"
claude "Restart all stopped VMs in the staging namespace"
claude "Show me the configuration of the database VM"
```
#### 故障排除
```bash
# VM diagnostics
claude "The payment-service VM isn't responding, can you investigate?"
claude "Compare the instance types of VMs in prod vs staging"
claude "What VMs are currently running and what resources are they using?"
```
#### 批量操作
```bash
# Mass management
claude "Stop all VMs in the test namespace"
claude "List all VMs that don't have instance types assigned"
claude "Show me a summary of VM status across all namespaces"
```
#### 开发工作流程
```bash
# Development tasks
claude "Start my development VMs (web-dev, db-dev, cache-dev)"
claude "Check if my feature branch VMs are ready for testing"
claude "Clean up any VMs from old feature branches"
```
### 可用功能
MCP 服务器为 Claude 提供以下工具：
**VM 生命周期：**
- `list_vms` - 列出命名空间中的 VM
- `start_vm` - 启动特定的 VM
- `stop_vm` - 停止特定的 VM
- `restart_vm` - 重启 VM
- `pause_vm` - 暂停 VM
- `unpause_vm` - 取消暂停 VM
- `create_vm` - 使用容器磁盘（支持操作系统名称，如“fedora”、“ubuntu”）和可选的 instancetype/preference 创建新的 VM
- `delete_vm` - 删除 VM
- `patch_vm` - 应用 JSON 合并补丁以修改 VM 配置
**VM 信息：**
- `get_vm_status` - 获取全面的 VM 状态信息
- `get_vm_conditions` - 获取详细的 VM condition 信息
- `get_vm_phase` - 获取当前 VM 阶段和基本状态
- `get_vm_instancetype` - 获取 VM 的分配实例类型
- `get_vm_disks` - 检索附加到虚拟机的磁盘列表
**实例类型和 Preferences：**
- `list_instancetypes` - 列出可用的实例类型
- `get_instancetype` - 获取有关特定实例类型的详细信息
- `get_preference` - 获取有关特定 preference 的详细信息
**Prompts：**
- `describe_vm` - 全面的 VM 描述和分析
- `troubleshoot_vm` - VM 故障排除和诊断
- `health_check_vm` - 快速 VM 健康检查
**容器磁盘查找：**
`create_vm` 工具支持完整的容器镜像 URL 和操作系统名称快捷方式：
- **操作系统名称**：`"fedora"`、`"ubuntu"`、`"centos"`、`"debian"`、`"rhel"`、`"opensuse"`、`"alpine"`、`"cirros"`、`"windows"`、`"freebsd"`
- **完整 URL**：`"quay.io/containerdisks/fedora:latest"`、`"my-registry/my-image:tag"`
- **自动解析**：未知的操作系统名称将解析为 `quay.io/containerdisks/{name}:latest`
**结构化数据：**
- `kubevirt://{namespace}/vms` - VM 摘要数据
- `kubevirt://{namespace}/vm/{name}` - 完整的 VM 规范
- `kubevirt://{namespace}/vmis` - VM 实例运行时数据
- `kubevirt://{namespace}/vmi/{name}` - 完整的 VMI 规范
### 安全注意事项
- **权限**：MCP 服务器使用您的 KUBECONFIG 凭据
- **范围**：Claude 具有与您的 kubeconfig 相同的 KubeVirt 权限
- **最佳实践**：考虑使用具有有限权限的专用服务帐户：
```bash
# Create a dedicated service account for MCP operations
kubectl create serviceaccount kubevirt-mcp-user
kubectl create clusterrole kubevirt-mcp-role \
--verb=get,list,create,update,patch,delete \
--resource=virtualmachines,virtualmachineinstances
kubectl create clusterrolebinding kubevirt-mcp-binding \
--clusterrole=kubevirt-mcp-role \
--serviceaccount=default:kubevirt-mcp-user
# Generate kubeconfig for the service account
kubectl create token kubevirt-mcp-user > /path/to/mcp-kubeconfig
```
### 故障排除
**连接问题：**
```bash
# Test MCP server manually
export KUBECONFIG=/path/to/your/kubeconfig
echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' | ./kubevirt-mcp-server
```
**权限问题：**
```bash
# Verify kubeconfig access
kubectl auth can-i get virtualmachines
kubectl auth can-i create virtualmachines
```
**Claude CLI 调试：**
```bash
# Enable verbose logging
claude --verbose "List my VMs"
# Check MCP server logs
CLAUDE_MCP_DEBUG=1 claude "List VMs in default namespace"
```
### 高级用法
**项目特定的 VM 管理：**
```bash
# Create a .clauderc for your project
cat > .clauderc << 'EOF'
{
"mcp": {
"servers": {
"kubevirt": {
"command": "/usr/local/bin/kubevirt-mcp-server",
"env": {
"KUBECONFIG": "./k8s/kubeconfig",
"DEFAULT_NAMESPACE": "myproject-dev"
}
}
}
},
"context": {
"project": "MyProject Development VMs",
"defaultNamespace": "myproject-dev"
}
}
EOF
# Now Claude understands your project context
claude "Start my development environment"
claude "Show me the status of project VMs"
```
## 演示
这个简短的演示使用 mcp-cli 作为 kubevirt-mcp-server 和 LLM 之间的桥梁。
演示使用的模型是 llama3.2，在 ollama 下本地运行。
<img src="demo.gif">
## 链接
- https://www.anthropic.com/news/model-context-protocol
- https://github.com/mark3labs/mcp-go
- https://github.com/chrishayuk/mcp-cli
