# TKE MCP Server - CodeBuddy 上下文文档

## 项目概述

**腾讯云 TKE MCP Server** 是一个基于 Model Context Protocol (MCP) 的腾讯云容器服务(TKE)管理工具，提供标准化的TKE集群管理接口。

### 核心技术栈
- **语言**: Python 3.10+
- **框架**: MCP (Model Context Protocol)
- **云服务**: 腾讯云 TKE (Tencent Kubernetes Engine)
- **包管理**: Hatch (通过 pyproject.toml)
- **测试框架**: unittest

### 主要功能
- **集群生命周期管理**: 创建、删除、修改集群属性、查询集群列表
- **动态工具加载**: 支持通过 OpenAPI 定义自动生成 MCP 工具
- **MCP 协议兼容**: 与 Claude Desktop 等 MCP 客户端集成

## 项目结构

```
tke-mcp/
├── src/mcp_server_tke/          # 主源代码目录
│   ├── __init__.py             # 模块入口点
│   ├── server.py               # MCP 服务器主逻辑
│   ├── tool_tke.py             # TKE 静态工具实现
│   ├── client.py               # 腾讯云客户端封装
│   ├── mcpapi_loader.py        # McpAPI YAML 文件加载器
│   ├── dynamic_tool_handler.py # 动态工具处理器
│   └── mcpapi/                 # 动态工具定义文件
├── openapi/                    # 云API导出的 OpenAPI 源文件目录
├── tests/                      # 单元测试
├── pyproject.toml              # Python 项目配置
└── README.md                   # 项目说明文档
```

## 构建和运行

### 安装依赖
```bash
pip install mcp-server-tke
# 或从源码安装
pip install .
```

### 配置腾讯云凭证
```bash
export TENCENTCLOUD_SECRET_ID=你的SecretId
export TENCENTCLOUD_SECRET_KEY=你的SecretKey
```

### 运行服务器
```bash
# 直接运行
uv run mcp-server-tke

# 或通过 Python 模块
python -m mcp_server_tke
```

### 测试
```bash
# 运行所有测试
python -m unittest discover tests/

# 运行特定测试文件
python -m unittest tests/test_tool_tke.py
```

### 构建包
```bash
# 使用 hatch 构建
hatch build
```

## 开发约定

### 代码风格
- **Python 3.10+** 语法特性
- **类型注解**: 使用 Python 类型提示
- **错误处理**: 统一的异常处理和日志记录
- **模块化**: 功能模块分离，便于扩展

### 测试实践
- **单元测试**: 每个模块都有对应的测试文件
- **模拟测试**: 在没有腾讯云凭证时使用模拟模式
- **参数验证**: 严格的输入参数验证

## 核心模块说明

### server.py
MCP 服务器主模块，处理工具列表请求和工具调用：
- `handle_list_tools()`: 返回可用工具列表（静态 + 动态）
- `handle_call_tool()`: 处理工具调用请求
- `serve()`: 启动 MCP 服务

### tool_tke.py
静态 TKE 工具实现，目前支持：
- `create_cluster()`: 创建 TKE 集群
- 参数验证和请求构建逻辑

### dynamic_tool_handler.py
动态工具处理器：
- 从 YAML 文件加载工具定义
- 动态生成 MCP 工具 schema
- 处理动态工具调用

### mcpapi_loader.py
McpAPI YAML 文件加载器：
- 扫描 `mcpapi/` 目录
- 解析 YAML 文件为 Python 字典
- 错误处理和日志记录

### client.py
腾讯云客户端封装：
- 认证信息管理
- TKE 客户端和通用客户端创建

## 工具定义格式

McpAPI YAML 文件格式示例：
```yaml
tools:
  - name: DeleteCluster
    description: 删除集群
    args:
      - name: ClusterId
        description: 集群ID
        type: string
        required: true
    requestTemplate:
      url: /DeleteCluster
      method: POST
    responseTemplate:
      prependBody: API响应信息...
```

## 错误处理

- **参数验证错误**: 返回明确的错误信息
- **API 调用错误**: 记录详细日志并返回用户友好信息
- **文件加载错误**: 忽略格式错误的文件，继续加载其他文件

## 部署和运维说明

### 生产环境部署

#### Docker 容器部署
```bash
# 构建 Docker 镜像
docker build -t tke-mcp-server .

# 运行容器
docker run -d --name tke-mcp-server \
  -p 8000:8000 \
  -e TENCENTCLOUD_SECRET_ID=你的SecretId \
  -e TENCENTCLOUD_SECRET_KEY=你的SecretKey \
  tke-mcp-server
```

#### Kubernetes 部署
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tke-mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: tke-mcp-server
  template:
    metadata:
      labels:
        app: tke-mcp-server
    spec:
      containers:
      - name: tke-mcp-server
        image: tke-mcp-server:latest
        ports:
        - containerPort: 8000
        env:
        - name: TENCENTCLOUD_SECRET_ID
          valueFrom:
            secretKeyRef:
              name: tencent-cloud-credentials
              key: secretId
        - name: TENCENTCLOUD_SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: tencent-cloud-credentials
              key: secretKey
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
```

### 监控和日志

#### 健康检查端点
```bash
# 健康检查
curl http://localhost:8000/health

# 就绪检查  
curl http://localhost:8000/ready

# 存活检查
curl http://localhost:8000/live
```

#### 性能监控指标
项目暴露以下监控指标：
- `mcp_requests_total`: 总请求数
- `mcp_request_duration_seconds`: 请求耗时
- `mcp_tools_loaded`: 加载的工具数量
- `mcp_connections_active`: 活跃连接数

### 性能优化指南

#### 内存优化
```python
# 使用 LRU 缓存工具定义
from functools import lru_cache

@lru_cache(maxsize=100)
def load_tool_definition(tool_name):
    """缓存工具定义，减少重复加载"""
    return load_tool_from_yaml(tool_name)
```

#### 连接池优化
```python
# 配置腾讯云客户端连接池
import httpx

async with httpx.AsyncClient(
    limits=httpx.Limits(max_connections=100, max_keepalive_connections=20),
    timeout=30.0
) as client:
    # 使用连接池进行API调用
    response = await client.post(api_url, json=payload)
```

### 故障排查指南

#### 常见问题排查

1. **认证失败**
```bash
# 检查凭证配置
echo $TENCENTCLOUD_SECRET_ID
echo $TENCENTCLOUD_SECRET_KEY

# 测试凭证有效性
curl -X POST https://tke.tencentcloudapi.com \
  -H "Content-Type: application/json" \
  -d '{"Action": "DescribeClusters", "Version": "2018-05-25"}'
```

2. **工具加载失败**
```bash
# 检查 YAML 文件格式
python -c "import yaml; yaml.safe_load(open('mcpapi/tool.yaml'))"

# 验证工具定义
python -m src.mcp_server_tke.mcpapi_loader --validate
```

3. **连接问题**
```bash
# 检查网络连通性
curl -v https://tke.tencentcloudapi.com

# 检查防火墙规则
iptables -L -n | grep 8000
```

#### 日志分析

启用详细日志记录：
```bash
# 设置调试日志级别
export LOG_LEVEL=DEBUG

# 启用请求日志
export REQUEST_LOGGING=true

# 查看详细日志
tail -f /var/log/tke-mcp-server.log | grep -E "(ERROR|WARN|DEBUG)"
```

### 高可用配置

#### 负载均衡配置
```nginx
# Nginx 配置
upstream tke_mcp_servers {
    server 10.0.1.10:8000;
    server 10.0.1.11:8000;
    server 10.0.1.12:8000;
    keepalive 32;
}

server {
    listen 80;
    location / {
        proxy_pass http://tke_mcp_servers;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}
```

#### 自动扩缩容
```yaml
# HPA 配置
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: tke-mcp-server
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: tke-mcp-server
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
```

### 备份和恢复

#### 配置备份
```bash
# 备份工具定义文件
tar -czf mcpapi-backup-$(date +%Y%m%d).tar.gz mcpapi/

# 备份配置文件
cp config.yaml config.yaml.backup
```

#### 灾难恢复
```bash
# 从备份恢复
tar -xzf mcpapi-backup-20250916.tar.gz
cp config.yaml.backup config.yaml

# 重启服务
docker restart tke-mcp-server
```

## 安全注意事项

### 访问控制
- 使用 Kubernetes Network Policies 限制网络访问
- 配置适当的 RBAC 权限
- 定期轮换腾讯云凭证

### 数据传输安全
- 使用 HTTPS 加密所有通信
- 启用 TLS 终止
- 使用安全的证书管理

### 资源限制
- 设置内存和 CPU 限制
- 配置请求超时
- 限制并发连接数

## Claude Desktop 配置

编辑 `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "tencent-tke": {
      "command": "uv",
      "args": ["run", "mcp-server-tke"],
      "env": {
        "TENCENTCLOUD_SECRET_ID": "你的SecretId",
        "TENCENTCLOUD_SECRET_KEY": "你的SecretKey",
        "LOG_LEVEL": "INFO",
        "MAX_CONNECTIONS": "100"
      }
    }
  }
}
```

## 注意事项

- 需要有效的腾讯云凭证才能调用真实 API
- 在没有凭证时会使用模拟模式
- 动态工具依赖于正确的 YAML 文件格式
- 所有地域参数必须使用腾讯云标准地域代码
- 定期监控服务性能和资源使用情况

## 许可证

MIT License - 详见项目根目录的 LICENSE 文件

---

*此文档基于项目代码分析和 README 生成，最后更新: 2025-09-16*