# TKE MCP服务器使用指南

本文档提供了TKE MCP服务器的完整使用指南，包括安装、配置和使用说明。

## 快速开始

### 1. 环境准备

确保你的系统满足以下要求：
- Python 3.10+
- 腾讯云账号和API密钥（可选，支持模拟模式）

### 2. 安装依赖

```bash
# 安装腾讯云SDK（可选，不安装将使用模拟模式）
pip install tencentcloud-sdk-python-tke==3.0.1356

# 安装MCP库（生产环境需要）
pip install mcp>=1.0.0

# 或安装所有依赖
pip install mcp-server-tke
```

### 3. 配置环境变量

```bash
export TENCENTCLOUD_SECRET_ID="your_secret_id"
export TENCENTCLOUD_SECRET_KEY="your_secret_key"
```

### 4. 启动服务器

```bash
# 方法1: 直接运行模块
python -m mcp_server_tke

# 方法2: 使用uv运行
uv run mcp-server-tke
```

## 功能说明

### 支持的工具

TKE MCP服务器提供以下工具：

#### 1. CreateCluster - 创建TKE集群（静态工具）

**功能**: 创建腾讯云容器服务(TKE)集群

**参数**:
- `Region` (必填): 地域，如 "ap-guangzhou"
- `ClusterBasicSettings.ClusterName` (可选): 集群名称
- `ClusterBasicSettings.ClusterLevel` (可选): 集群规格，默认L50
- `ClusterBasicSettings.ClusterOs` (必填): 操作系统镜像ID
- `ClusterBasicSettings.VpcId` (必填): 私有网络ID
- `ClusterCIDRSettings.EniSubnetIds` (必填): 子网ID列表
- `ClusterCIDRSettings.ServiceCIDR` (必填): Service CIDR

**返回值**: JSON格式的API响应，包含集群ID

**示例**:
```json
{
  "Region": "ap-guangzhou",
  "ClusterBasicSettings.ClusterName": "my-tke-cluster",
  "ClusterBasicSettings.ClusterLevel": "L50",
  "ClusterBasicSettings.ClusterOs": "ubuntu18.04.1x86_64",
  "ClusterBasicSettings.VpcId": "vpc-12345678",
  "ClusterCIDRSettings.EniSubnetIds": ["subnet-12345678"],
  "ClusterCIDRSettings.ServiceCIDR": "10.96.0.0/12"
}
```

#### 2. DeleteCluster - 删除TKE集群（动态工具）

**功能**: 删除指定的TKE集群

**参数**:
- `Region` (必填): 地域，如 "ap-guangzhou"
- `ClusterId` (必填): 集群ID，格式为 cls-xxxxxxxx
- `InstanceDeleteMode` (可选): 实例删除模式，默认 "retain"
- `ResourceDeleteOptions` (可选): 资源删除选项数组

**返回值**: JSON格式的API响应

**示例**:
```json
{
  "Region": "ap-guangzhou",
  "ClusterId": "cls-12345678",
  "InstanceDeleteMode": "retain"
}
```

#### 3. ModifyClusterAttribute - 修改集群属性（动态工具）

**功能**: 修改TKE集群的属性

**参数**:
- `Region` (必填): 地域
- `ClusterId` (必填): 集群ID
- `ClusterName` (可选): 新的集群名称
- `ClusterDescription` (可选): 集群描述
- `ProjectId` (可选): 项目ID

#### 4. DescribeClusters - 查询集群列表（动态工具）

**功能**: 查询TKE集群列表

**参数**:
- `Region` (必填): 地域
- `ClusterIds` (可选): 集群ID列表
- `ClusterType` (可选): 集群类型
- `Limit` (可选): 最大输出条数
- `Offset` (可选): 偏移量

#### 5. DescribeClusterKubeconfig - 获取集群kubeconfig（动态工具）

**功能**: 获取TKE集群的kubeconfig文件

**参数**:
- `Region` (必填): 地域
- `ClusterId` (必填): 集群ID
- `IsExtranet` (可选): 是否外网访问

## 动态工具系统

### McpAPI文件格式

动态工具通过YAML文件定义，位于 `src/mcp_server_tke/mcpapi/` 目录。文件格式示例：

```yaml
tools:
  - name: DeleteCluster
    description: 删除集群
    args:
      - name: ClusterId
        description: 集群ID
        type: string
        required: true
    requestTemplate:
      url: /DeleteCluster
      method: POST
    responseTemplate:
      prependBody: API响应信息...
```

### 自动加载机制

服务器启动时会自动扫描 `mcpapi/` 目录，解析所有YAML文件并生成对应的MCP工具。支持：
- 嵌套对象参数
- 数组类型参数
- 枚举值验证
- 默认值设置

## 模拟模式

当没有配置腾讯云凭证或SDK未安装时，服务器会自动进入模拟模式：
- 返回模拟的API响应
- 包含有效的RequestId和模拟数据
- 支持开发和测试环境

## 使用示例

### 基本用法

```python
from mcp_server_tke.tool_tke import create_cluster

# 创建集群
create_params = {
    "Region": "ap-guangzhou",
    "ClusterBasicSettings.ClusterName": "test-cluster",
    "ClusterBasicSettings.ClusterOs": "ubuntu18.04.1x86_64",
    "ClusterBasicSettings.VpcId": "vpc-example",
    "ClusterCIDRSettings.EniSubnetIds": ["subnet-example"],
    "ClusterCIDRSettings.ServiceCIDR": "10.96.0.0/12"
}

result = create_cluster(create_params)
print(result)
```

### 错误处理

```python
try:
    result = create_cluster(params)
    print("集群创建成功:", result)
except ValueError as e:
    print("参数验证错误:", e)
except Exception as e:
    print("API调用失败:", e)
```

### 客户端配置

```python
import os
from mcp_server_tke.client import get_tke_client

# 设置环境变量
os.environ["TENCENTCLOUD_SECRET_ID"] = "your_secret_id"
os.environ["TENCENTCLOUD_SECRET_KEY"] = "your_secret_key"

# 获取客户端
client = get_tke_client("ap-guangzhou")
```

## 测试和验证

### 运行测试套件

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

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

## 生产环境部署

### Docker部署

```dockerfile
FROM python:3.10-slim

WORKDIR /app

# 安装依赖
COPY pyproject.toml .
RUN pip install .

# 复制源码
COPY src/ ./src/

# 设置环境变量
ENV TENCENTCLOUD_SECRET_ID=""
ENV TENCENTCLOUD_SECRET_KEY=""

# 启动服务
CMD ["python", "-m", "mcp_server_tke"]
```

### 系统服务

```ini
# /etc/systemd/system/tke-mcp-server.service
[Unit]
Description=TKE MCP Server
After=network.target

[Service]
Type=simple
User=mcp
WorkingDirectory=/opt/tke-mcp-server
Environment=TENCENTCLOUD_SECRET_ID=your_secret_id
Environment=TENCENTCLOUD_SECRET_KEY=your_secret_key
ExecStart=/usr/bin/python -m mcp_server_tke
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

## 故障排除

### 常见问题

1. **模块导入错误**
   - 确保Python路径正确
   - 检查依赖是否安装

2. **腾讯云API调用失败**
   - 检查访问密钥配置
   - 确认地域参数正确
   - 验证网络连接

3. **参数验证失败**
   - 检查必填参数是否提供
   - 验证参数格式是否正确

4. **动态工具加载失败**
   - 检查mcpapi目录下的YAML文件格式
   - 确认文件编码为UTF-8

### 日志配置

```python
import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
```

## API参考

详细的API参考请参见：
- [腾讯云TKE API文档](https://cloud.tencent.com/document/product/457)
- [MCP协议规范](https://spec.modelcontextprotocol.io/)

## 支持和反馈

如有问题或建议，请通过以下方式联系：
- 提交Issue到项目仓库
- 查看测试报告和验证结果
- 参考示例代码和文档
