内容
# mcp-k8s-deployer
[](https://github.com/stwins60/mcp-k8s-deployer/releases)
[](https://pypi.org/project/mcp-k8s-deployer/)
[](https://opensource.org/licenses/MIT)
一个生产就绪的模型上下文协议（MCP）服务器，能够赋予LLMs动态编排容器化应用部署到Kubernetes集群的能力。
它处理配置验证、交互式存储解析、多资源清单生成（命名空间、持久卷声明、部署、服务）、干燥运行计划审查、实际应用操作以及服务端点提取，针对`cloudflared`隧道路由进行了优化。
---
## 功能
- **交互式存储解析**：动态检查是创建新的持久卷声明（PVC）、绑定到现有的持久卷（PV），还是需要用户提供更多详细信息，取决于存储类别是否与集群的默认NFS设置匹配。
- **严格的输入验证**：强制执行RFC 1123合规的命名规则，用于应用、命名空间和存储类别，验证端口范围、副本数、镜像标签和Kubernetes存储大小（例如`10Gi`）。
- **干燥运行计划和实际应用**：公开单独的计划（`plan_deployment`）和应用（`apply_deployment`）阶段。计划运行Kubernetes服务器端干燥运行，以在提交更改之前捕获配置错误。
- **强制审查步骤**：`apply_deployment`工具需要明确的`approved=True`参数，以强制用户验证计划的更改。
- **隧道映射助手**：自动格式化端点，以无缝配置具有`cloudflared`隧道的公共子域。
---
## 先决条件
- **Python**：版本3.10或更高。
- **Kubernetes集群**：访问正在运行的集群（例如k3s、minikube、GKE、EKS），并具有集群凭证。
- **凭证**：有效的kubeconfig文件（默认为`~/.kube/config`）。
---
## 安装
### 从PyPI（推荐）
```bash
pip install mcp-k8s-deployer
```
### 从源码
```bash
git clone https://github.com/stwins60/mcp-k8s-deployer.git
cd mcp-k8s-deployer
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 验证安装
```bash
python3 -m pytest -v
```
---
## 配置
服务器支持通过环境变量或YAML配置文件进行配置。
### 环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
| `MCP_K8S_LOG_LEVEL` | 日志级别（`DEBUG`、`INFO`、`WARNING`、`ERROR`） | `INFO` |
| `MCP_K8S_DEFAULT_NFS_STORAGE_CLASS` | 默认NFS存储类别名称 | `nfs` |
| `MCP_K8S_ALLOWED_NAMESPACES` | 允许的命名空间列表（逗号分隔）。如果为空，则允许所有命名空间。 | `""` |
| `KUBECONFIG` 或 `MCP_K8S_KUBECONFIG_PATH` | 活动集群的kubeconfig文件路径 | `~/.kube/config` |
| `MCP_K8S_DEFAULT_REPLICAS` | 未指定的默认Pod副本数 | `1` |
| `MCP_K8S_DEFAULT_PORT` | 未指定的默认服务端口 | `80` |
| `MCP_K8S_DEFAULT_STORAGE_SIZE` | 默认持久卷大小 | `10Gi` |
### YAML配置文件
在项目的根目录下创建一个`config.yaml`文件（或存储在`/etc/mcp-k8s/config.yaml`）：
```yaml
logging:
level: "INFO"
kubernetes:
kubeconfig_path: "" # 空值使用默认 ~/.kube/config
default_nfs_storage_class: "nfs"
allowed_namespaces: []
defaults:
replicas: 1
container_port: 80
storage_size: "10Gi"
```
---
## 暴露的MCP工具
### 1. `choose_storage_option_tool`
根据存储类别和持久卷需求评估存储配置。
* **参数**：
- `storage_class`（字符串，必填）：目标存储类别名称（例如`nfs`、`local-path`）。
- `has_existing_pv`（布尔值，必填）：用户是否已创建持久卷（PV）。
- `existing_pv_name`（字符串，可选）：要静态绑定的现有持久卷名称。
- `storage_size`（字符串，可选）：期望的磁盘大小（例如`5Gi`）。
- `default_nfs_class`（字符串，可选）：覆盖默认NFS存储类别配置。
* **返回**：一个JSON字典，指导持久卷声明生成、持久卷绑定或所需操作。
### 2. `deploy_app_tool`
收集配置、验证输入并生成Kubernetes清单（YAML格式）。
* **参数**：
- `app_name`（字符串，必填）
- `image`（字符串，必填）
- `container_port`（整数，必填）
- `replicas`（整数，可选）
- `namespace`（字符串，可选）
- `use_persistence`（布尔值，可选）
- `storage_class`（字符串，可选）
- `storage_size`（字符串，可选）
- `existing_pv_name`（字符串，可选）
- `env_vars`（字典，可选）
- `hostname`（字符串，可选）
* **返回**：一个多文档YAML字符串，代表命名空间、持久卷声明、部署和服务。
### 3. `plan_deployment_tool`
验证输入、生成清单并运行**服务器端干燥运行应用**针对集群。
* **参数**：与`deploy_app_tool`相同。
* **返回**：生成的清单、干燥运行操作列表（例如`Created`、`Patched`）和验证状态。
### 4. `apply_deployment_tool`
将批准的清单应用于Kubernetes集群。
* **参数**：
- `manifests`（字符串，必填）：生成的YAML清单。
- `approved`（布尔值，必填）：必须设置为`True`以确认。
* **返回**：成功状态和创建或修补的资源数组。
### 5. `create_namespace_tool`
如果命名空间不存在，则创建它。
* **参数**：
- `namespace`（字符串，必填）
- `dry_run`（布尔值，可选）
### 6. `get_service_endpoint_tool`
计算内部集群服务DNS端点。
* **参数**：`app_name`（字符串）、`namespace`（字符串）、`container_port`（整数）。
* **返回**：服务URL（例如`http://app.namespace.svc.cluster.local:80`）。
### 7. `build_cloudflared_target_tool`
生成确切的目标字符串，以粘贴到cloudflared隧道映射配置中。
* **参数**：`app_name`（字符串）、`namespace`（字符串）、`container_port`（整数）。
---
## Claude桌面集成
### 使用pip安装的软件包
将以下内容添加到您的Claude桌面配置（Linux上的`~/.config/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"kubernetes-deployer": {
"command": "mcp-k8s-deployer",
"env": {
"MCP_K8S_DEFAULT_NFS_STORAGE_CLASS": "nfs",
"MCP_K8S_LOG_LEVEL": "INFO"
}
}
}
}
```
### 使用本地源代码checkout
```json
{
"mcpServers": {
"kubernetes-deployer": {
"command": "/path/to/.venv/bin/python3",
"args": [
"/path/to/mcp-k8s-deployer/src/server.py"
],
"env": {
"MCP_K8S_DEFAULT_NFS_STORAGE_CLASS": "nfs",
"MCP_K8S_LOG_LEVEL": "INFO"
}
}
}
}
```
---
## 传输选择（Stdio vs SSE）
默认情况下，服务器在标准输入/输出（**stdio**）传输上运行，适用于Claude Desktop等本地集成。
### 在Stdio上运行（默认）
```bash
python3 src/server.py --transport stdio
```
### 在SSE上运行（HTTP Web服务器）
```bash
python3 src/server.py --transport sse --host 0.0.0.0 --port 8000
```
或使用环境变量：
```bash
export MCP_TRANSPORT=sse
export MCP_PORT=8000
python3 src/server.py
```
MCP端点将在`http://<your-host>:8000/sse`上可访问。
---
## 典型执行流程
1. **用户请求**：*“部署我的Node.js应用`auth-service`，使用`node:18`在`dev`命名空间中。它需要5Gi的gp2存储。”*
2. **存储决策**：LLM调用`choose_storage_option_tool(storage_class="gp2", has_existing_pv=False, storage_size="5Gi")`。
3. **存储建议**：服务器建议`gp2`是非默认的，并将依赖动态配置。LLM将此呈递给用户。
4. **规划**：用户确认。LLM调用`plan_deployment_tool(...)`，返回计划的资源和干燥运行状态。
5. **确认**：LLM呈现YAML清单供用户审查。
6. **执行**：用户确认。LLM调用`apply_deployment_tool(manifests="...", approved=True)`。
7. **映射**：LLM调用`build_cloudflared_target_tool(...)`并打印Cloudflare Tunnel入口目标（例如`http://auth-service.dev.svc.cluster.local:80`）。
---
## 分发
### PyPI
该软件包通过GitHub Actions使用OIDC受信任发布自动发布到PyPI，无需API令牌。
要发布新版本：
1. 更新`pyproject.toml`中的`version`
2. 提交并推送到`master`
3. 使用版本标签（例如`v1.0.1`）创建新的GitHub发布
工作流在`.github/workflows/publish.yml`将自动构建并上传到PyPI。
### Docker
```bash
# 构建容器镜像
docker build -t your-dockerhub-username/mcp-k8s-deployer:latest .
# 推送到Docker Hub
docker push your-dockerhub-username/mcp-k8s-deployer:latest
```
### Docker Compose & Cloudflare Tunnel
1. 使用您的Cloudflare令牌创建`.env`文件：
```env
CLOUDFLARE_TUNNEL_TOKEN=your_cloudflare_tunnel_token_here
```
2. 启动服务：
```bash
docker compose up -d
```
3. 在您的Cloudflare Zero Trust仪表板中，配置一个**公共主机名**：
- **域名**：`mcp.yourdomain.com`
- **服务类型**：`HTTP`
- **URL**：`mcp-server:8000`
您的MCP服务器将在`https://mcp.yourdomain.com/sse`上可访问。
---
## 链接
- **PyPI**：https://pypi.org/project/mcp-k8s-deployer/
- **GitHub**：https://github.com/stwins60/mcp-k8s-deployer
- **问题**：https://github.com/stwins60/mcp-k8s-deployer/issues
---
## 许可证
MIT
