内容
# kubeaid-mcp
MCP（模型上下文协议）服务器，适用于任何与MCP兼容的AI客户端（Claude Code、Claude Desktop、Cursor等）。客户端将二进制文件作为子进程启动，并通过stdio（JSON-RPC 2.0）与其通信；服务器通过`client-go`将工具调用转换为Kubernetes API调用。
详见 [design.md](./design.md) 了解架构。
## 工具列表
| 工具 | 描述 |
|------|-------------|
| `list_contexts` | 列出服务器可以针对的kubeconfig上下文（集群）。 |
| `list_namespaces` | 列出集群中的命名空间及其状态。 |
| `list_pods` | 列出命名空间（或所有命名空间）中的Pod，包含派生状态、就绪计数、重启次数和年龄。 |
| `describe_pod` | Pod状态、每个容器的状态（等待/终止原因、最后重启）和近期事件。 |
| `get_pod_logs` | 尾部查看容器的日志；`previous: true` 读取崩溃实例的前期日志。 |
| `list_deployments` | 列出部署及其就绪/最新/可用副本计数和年龄。 |
| `list_nodes` | 列出集群节点及其就绪状态、角色、版本和内部IP。 |
| `get_events` | 命名空间（或所有）中的近期事件，按时间排序从旧到新。 |
| `describe_resource` | 通过动态客户端按类型/复数/简称和名称获取任何资源类型（包括CRDs）。 |
每个工具都接受一个可选的 `context` 参数，以针对特定的kubeconfig上下文。省略它以使用服务器的默认上下文。
### 编写工具（需选择加入）
这些工具仅在设置 `--allow-writes` 时注册。每个工具都接受一个可选的 `dry_run` 参数，以在服务器端模拟更改而不持久化。
| 工具 | 描述 |
|------|-------------|
| `apply_manifest` | 从YAML/JSON清单中创建或更新资源（服务器端应用）。 |
| `patch_resource` | 修补现有资源（策略性/合并/ JSON）。 |
| `delete_resource` | 按类型和名称删除资源。 |
| `scale_deployment` | 设置部署的副本计数。 |
| `rollout_restart` | 滚动重启部署/有状态集/守护进程集。 |
| `exec_command` | 在容器内运行命令（仅限 `--allow-exec`）。 |
## 提示
提示是用户调用的工作流模板（在客户端中显示为斜杠命令/菜单项）。与工具不同，提示不会触及集群 — 它会返回一条消息，指导模型通过上述工具完成任务。
| 提示 | 参数 | 执行操作 |
|--------|-----------|--------------|
| `diagnose_pod` | `namespace`, `pod_name`, `context?` | 逐步描述 → 日志以查找Pod不健康的原因并建议修复。 |
| `triage_namespace` | `namespace`, `context?` | 在命名空间中找到所有不健康的负载并进行调查。 |
| `cluster_health_check` | `context?` | 高级健康扫描：节点、所有命名空间的Pod、近期警告。 |
| `review_warnings` | `namespace?`, `context?` | 审查近期警告事件并解释其含义。 |
## 安装
安装一次二进制文件，然后将其注册到您的AI客户端。
### 1. 安装二进制文件
选择您喜欢的方式：
**Go安装**（需要Go 1.26+）：
```bash
go install github.com/1shubham7/kubeaid-mcp@latest
```
安装到 `$(go env GOPATH)/bin`（通常是 `~/go/bin`）- 确保它在您的 `PATH` 中。
**预编译发布二进制文件：** 从 [Releases](https://github.com/1shubham7/kubeaid-mcp/releases) 页面下载适用于您的操作系统/架构的存档，然后将其移动到 `PATH` 中：
```bash
tar xzf kubeaid-mcp-*-linux-amd64.tar.gz
sudo mv kubeaid-mcp /usr/local/bin/
```
**从源代码编译：**
```bash
git clone https://github.com/1shubham7/kubeaid-mcp.git
cd kubeaid-mcp
make install # 安装到 $GOBIN / ~/go/bin（版本戳）
# 或：make build # 仅在仓库中编译 ./kubeaid-mcp
```
然后记录绝对路径 - AI客户端需要它：
```bash
command -v kubeaid-mcp
```
### 2. 注册到 Claude Code
```bash
claude mcp add kubeaid -- "$(command -v kubeaid-mcp)" --context kind-kubeaid
```
用默认上下文替换 `kind-kubeaid`。重启Claude Code会话以获取工具（或重新编译二进制文件）。要启用写入，请追加标志：
```bash
claude mcp add kubeaid -- "$(command -v kubeaid-mcp)" \
--context kind-kubeaid --allow-writes \
--protected-context prod-cluster,another-prod-cluster
```
### 3. 注册到 Claude Desktop
最近的Claude Desktop版本在设置中启用了本地MCP服务器，因此顺序很重要：
1. **启用本地MCP：** 设置 → 开发者 → **本地MCP服务器**。默认情况下，本地_stdio服务器是关闭的；打开/启用此选项是必需的。
2. **编辑配置：** 在该页面上点击 **编辑配置** - 它打开应用程序实际读取的文件（Linux上的 `~/.config/Claude/claude_desktop_config.json`；macOS上的 `~/Library/Application Support/Claude/`；Windows上的 `%APPDATA%\Claude\`）。添加顶级 `mcpServers` 键，使用步骤1中的绝对路径：
```json
{
"mcpServers": {
"kubeaid": {
"command": "/home/you/go/bin/kubeaid-mcp",
"args": ["--context", "kind-kubeaid"]
}
}
}
```
如果文件已经有其他键（例如 `preferences`），请保留它们并在旁边添加 `mcpServers` - 不要覆盖文件。
3. **完全退出并重新打开** Claude Desktop。在Linux上，关闭窗口是不够的 - 进程必须实际退出。然后，服务器出现在设置 → 开发者 → 本地MCP服务器下。
**启用写入：** 在 `args` 中添加标志 - 例如，使本地集群可写入，同时保护生产环境：
```json
{
"mcpServers": {
"kubeaid": {
"command": "/home/you/go/bin/kubeaid-mcp",
"args": [
"--context", "kind-kubeaid",
"--allow-writes",
"--protected-context", "prod-cluster,another-prod-cluster"
]
}
}
}
```
添加 `--allow-exec` 以获取 `exec_command` 工具，并在更改 `args` 后重新运行步骤3。
**注意：**
- `command` 必须是绝对路径；GUI应用程序不会继承您的shell `PATH`。
- 破坏性工具带有 `DestructiveHint`，因此桌面仍然会提示您进行每个操作 - 标志控制什么 *可能* ；提示是您的确认。
- 如果您的帐户是企业管理的，管理员策略可以完全禁用本地MCP，在这种情况下，本地配置将无法加载。
## 安全
服务器 **默认情况下为只读** - 读取工具仅调用非变异动词（get、list、watch、log）。变异工具存在但受到限制：
- 必须设置 `--allow-writes` 才能公开 `apply_manifest`、`patch_resource`、`delete_resource`、`scale_deployment` 和 `rollout_restart`。
- 额外需要 `--allow-exec`（除了上述条件）才能公开 `exec_command`。
- `--protected-context` 列出了 **禁止** 写入或执行操作的上下文 - 将您的生产环境上下文放在此处。
- 工具被注释（`ReadOnlyHint` / `DestructiveHint`），以便客户端在冒险操作之前提示。
服务器使用您的kubeconfig凭证进行身份验证，因此它只能执行您的帐户已经允许的操作。
## 标志
| 标志 | 默认值 | 含义 |
|------|---------|---------|
| `--kubeconfig` | `$KUBECONFIG` 或 `~/.kube/config` | kubeconfig文件的路径。 |
| `--context` | kubeconfig当前上下文 | 默认上下文；个别工具调用可以覆盖它。 |
| `--request-timeout` | `30s` | Kubernetes API调用的每个请求超时。 |
| `--allow-writes` | `false` | 公开变异工具（apply/patch/delete/scale/rollout）。 |
| `--allow-exec` | `false` | 公开 `exec_command`（在容器中运行命令）。 |
| `--protected-context` | 无 | 禁止写入或执行操作的上下文，以逗号分隔。 |
## 开发
手动驱动服务器（无需AI客户端）以检查原始协议：
```bash
python3 scripts/drive.py # 发送初始化 + 工具/列表 + 工具/调用
```
