# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 同步依赖：自动创建 .venv、按 pyproject.toml 解析并安装所有运行时依赖
uv sync

# 如需开发工具（pytest / pylint / black / mypy 等）
uv sync --extra dev

# 复制示例配置，按需修改 .env
cp env.example .env

# 默认 stdio 模式启动（推荐用于 MCP 客户端）
k8s-mcp-server

# 或明确指定 stdio 模式
k8s-mcp-server --transport stdio

# Streamable HTTP 模式启动（推荐 Cursor 等 HTTP MCP 客户端）
k8s-mcp-server --transport streamable --host 0.0.0.0 --port 8000

# SSE 模式启动（兼容旧 SSE 客户端）
k8s-mcp-server --transport sse --host 0.0.0.0 --port 8000

# 或使用 uvicorn 直接启动 HTTP 服务
uvicorn tools:app --host 0.0.0.0 --port 8000

{
  "mcpServers": {
    "k8s-mcp-server": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

{
  "mcpServers": {
    "k8s-mcp-server": {
      "command": "k8s-mcp-server",
      "args": ["--transport", "stdio"],
      "cwd": "项目路径"
    }
  }
}

# macOS / Linux
cp -r skills/k8s-manage ~/.cursor/skills/

# Windows
xcopy /E /I skills\k8s-manage %USERPROFILE%\.cursor\skills\k8s-manage

# 构建 Docker 镜像
docker build -t k8s-mcp-server:latest .

# 运行容器
docker run -d --name k8s-mcp-server \
  -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  k8s-mcp-server:latest

# 在 Kubernetes 中部署
kubectl apply -f k8s/

k8s-mcp-server/
├── services/
│   ├── __init__.py
│   ├── factory.py               # 服务实例工厂（按 kubeconfig_path 缓存）
│   ├── k8s_advanced_service.py  # Kubernetes 进阶服务（批量操作、备份恢复、RBAC、验证）
│   ├── dynamic_resource_service.py  # 动态资源服务（DynamicClient，支持 CRD 及任意 API 资源）
│   ├── k8s_api/                 # Kubernetes API 服务层（模块化）
│   │   ├── base.py, cluster_ops.py, pod_ops.py, workload_ops.py
│   │   ├── jobcronjob_ops.py, networking_storage_ops.py, service_config_ops.py
│   │   ├── autoscaling_policy_ops.py, rbac_ops.py, interactive_ops.py
│   │   └── resource_builders.py
│   └── k8s_advanced/            # 进阶服务逻辑（批量、备份、验证、RBAC）
│       ├── batch_ops.py, backup_restore.py, validation.py
│       ├── resource_conversion.py, rbac_advanced.py
│       └── base.py
├── tools/
│   ├── __init__.py              # FastMCP 实例和工具模块导入
│   ├── k8s_tools.py             # 核心 K8s 资源管理工具 (5个)
│   ├── cluster_tools.py         # 多集群配置管理 (9个)
│   ├── diagnostic_tools.py      # 集群诊断工具 (6个)
│   ├── batch_tools.py           # 批量操作工具 (8个)
│   ├── backup_tools.py          # 备份恢复工具 (4个)
│   └── auth_tools.py            # 认证与用户管理 (3个，仅认证模式可见)
├── utils/
│   ├── __init__.py
│   ├── cluster_config.py        # 集群配置管理类（支持多租户隔离）
│   ├── context.py               # 上下文管理
│   ├── fastmcp_custom.py        # 自定义 FastMCP（含 Tool 可见性过滤）
│   ├── auth_context.py          # 请求级用户上下文（contextvars）
│   ├── jwt_service.py           # JWT 签发/验证
│   ├── jwt_middleware.py        # ASGI JWT 认证中间件
│   ├── permission_profiles.py   # 权限 Profile 管理（内置 + 自定义）
│   ├── token_store.py           # JWT 签发记录持久化
│   ├── revocation_store.py      # JWT 撤销列表
│   ├── admin_routes.py          # 管理 API 路由
│   ├── k8s_helpers.py           # K8s 辅助函数
│   ├── k8s_parsers.py          # 参数解析
│   ├── param_parsers.py        # 参数解析
│   ├── operations_logger.py    # 操作日志
│   ├── backup_paths.py         # 备份路径
│   └── decorators.py, response.py, mcp_server.py
├── k8s/                         # Kubernetes 部署文件
│   ├── deployment.yaml          # 主要部署配置
│   ├── service.yaml             # 服务暴露配置
│   ├── configmap.yaml           # 配置管理
│   ├── pvc.yaml                 # 数据持久化
│   └── README.md                # 部署指南
├── data/
│   ├── clusters.json            # 集群配置存储
│   ├── kubeconfigs/             # kubeconfig 文件存储目录
│   ├── backup/                  # 备份存储（按集群/命名空间/资源类型层级）
│   └── copyfiles/               # Pod 文件拷贝本地保存目录
├── tests/                       # 回归测试
│   └── regression_test.py       # 同步/异步 37 个用例
├── skills/
│   └── k8s-manage/SKILL.md      # Skill（工具清单、参数、连接方式、操作流程）
├── docs/
│   └── TOOLS.md                 # 工具清单文档
├── Dockerfile                   # 容器镜像构建文件
├── .dockerignore                # Docker 构建排除文件
├── config.py                    # 服务配置
├── main.py                      # 服务启动入口
└── pyproject.toml               # 依赖列表

// 批量列出资源（使用默认集群配置）
{
  "method": "tools/call",
  "params": {
    "name": "batch_list_resources",
    "arguments": {
      "resource_types": "pods,nodes,namespaces",
      "namespace": "default"
    }
  }
}

// 批量删除资源（支持 grace_period_seconds）
{
  "method": "tools/call",
  "params": {
    "name": "batch_delete_resources",
    "arguments": {
      "resources": "[{\"kind\":\"Pod\",\"name\":\"my-pod\"}]",
      "namespace": "default",
      "grace_period_seconds": 30
    }
  }
}

// 批量创建资源
{
  "method": "tools/call",
  "params": {
    "name": "batch_create_resources",
    "arguments": {
      "resources": "[{\"kind\": \"Deployment\", \"metadata\": {\"name\": \"app1\"}, \"spec\": {\"name\": \"app1\", \"image\": \"nginx:latest\", \"replicas\": 3}}, {\"kind\": \"Service\", \"metadata\": {\"name\": \"app1-svc\"}, \"spec\": {\"name\": \"app1-svc\", \"selector\": {\"app\": \"app1\"}, \"ports\": [{\"port\": 80}]}}]",
      "namespace": "default"
    }
  }
}

// 备份命名空间
{
  "method": "tools/call",
  "params": {
    "name": "backup_namespace",
    "arguments": {
      "namespace": "my-app",
      "include_secrets": true
    }
  }
}

// 批量操作会自动显示验证和预览信息
// 更新操作会显示具体的变更内容，如：
// "📋 预览变化:"
// "   • replicas: 3 → 5"
// "   • labels.version: 1.0 → 2.0"

// 批量创建资源
{
  "method": "tools/call",
  "params": {
    "name": "batch_create_resources",
    "arguments": {
      "resources": [
        {
          "apiVersion": "apps/v1",
          "kind": "Deployment",
          "metadata": {"name": "app1", "namespace": "default"},
          "spec": {"replicas": 2, "selector": {"matchLabels": {"app": "app1"}}, "template": {"metadata": {"labels": {"app": "app1"}}, "spec": {"containers": [{"name": "app1", "image": "nginx:1.20"}]}}}
        },
        {
          "apiVersion": "v1",
          "kind": "Service",
          "metadata": {"name": "app1-svc", "namespace": "default"},
          "spec": {"selector": {"app": "app1"}, "ports": [{"port": 80, "targetPort": 80}]}
        }
      ],
      "namespace": "default"
    }
  }
}

// 批量更新Job的labels和annotations
{
  "method": "tools/call",
  "params": {
    "name": "batch_update_resources",
    "arguments": {
      "resources": [
        {
          "apiVersion": "batch/v1",
          "kind": "Job",
          "metadata": {
            "name": "job1",
            "namespace": "default",
            "labels": {"app": "batch-job", "version": "v2", "updated": "true"},
            "annotations": {"description": "Updated batch job", "last-modified": "2025-01-08"}
          }
        }
      ],
      "namespace": "default"
    }
  }
}

// 完全使用默认配置（集群和命名空间）
{
  "method": "tools/call",
  "params": {
    "name": "batch_list_resources",
    "arguments": {
      "resource_types": "pods",
      "namespace": "default"
    }
  }
}

{
  "success": true,
  "pods": [...],
  "count": 5,
  "namespace": "default"
}

# 构建镜像
docker build -t k8s-mcp-server:latest .

# 运行容器
docker run -d --name k8s-mcp-server \
  -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  k8s-mcp-server:latest

docker run -d \
  -e SSE_HOST=0.0.0.0 \
  -e SSE_PORT=8000 \
  -e LOG_LEVEL=INFO \
  -e DATA_DIR=/app/data \
  k8s-mcp-server:latest

# 部署所有资源
kubectl apply -f k8s/

# 查看部署状态
kubectl get pods -l app=k8s-mcp-server
kubectl get svc k8s-mcp-server

# 数据存储卷（含集群配置、kubeconfig、备份、用户操作日志等）
- name: data-volume
  persistentVolumeClaim:
    claimName: k8s-mcp-server-data

livenessProbe:
  tcpSocket:
    port: 8000
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  tcpSocket:
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 5

# SSE 服务配置
SSE_HOST=0.0.0.0
SSE_PORT=8000

# 数据存储目录（自动创建）
DATA_DIR=./data                 # 集群配置、kubeconfig、备份等数据根目录

# 备份保留策略（按文件修改时间计算，过期自动清理；0 表示永不清理）
MCP_BACKUP_RETENTION_DAYS=90    # 默认 90 天

# MCP 路径配置
MCP_STREAMABLE_PATH=/mcp        # Streamable HTTP 单端点
MCP_SSE_PATH=/sse               # SSE 连接端点
MCP_MESSAGE_PATH=/message       # SSE 消息 POST 端点

# 日志级别
LOG_LEVEL=info

# 认证配置（可选，默认不启用）
MCP_AUTH_ENABLED=false          # 设为 true 启用 JWT 认证和多租户隔离
MCP_JWT_SECRET=                 # JWT 签名密钥（启用认证时必填）
MCP_JWT_ALGORITHM=HS256         # JWT 算法
MCP_TOKEN_MAX_EXPIRY=7776000    # Token 最大有效期（秒），默认 90 天
MCP_ADMIN_API_PREFIX=/admin     # 管理 API 路由前缀

@mcp.tool()
async def my_new_tool(kubeconfig_path: str = None, namespace: str = "default") -> str:
    """新工具描述"""
    try:
        from services.factory import get_k8s_api_service
        from utils.response import json_success, json_error
        k8s_service = get_k8s_api_service(kubeconfig_path)  # 按 kubeconfig_path 缓存
        result = await k8s_service.some_api_call(namespace=namespace)
        return json_success({"data": result})
    except Exception as e:
        return json_error(str(e))

async def new_api_method(self, param1: str, grace_period_seconds: int = None) -> Dict[str, Any]:
    """新的 API 方法"""
    try:
        # 支持优雅删除
        body = client.V1DeleteOptions(grace_period_seconds=grace_period_seconds) if grace_period_seconds is not None else None
        
        # 使用 self.v1_api, self.apps_v1_api 等进行 API 调用
        result = self.v1_api.some_kubernetes_api(body=body)
        return self._format_result(result)
    except ApiException as e:
        raise Exception(f"API 调用失败: {e.reason}")

# 启动服务
k8s-mcp-server

# 在 MCP 客户端中导入集群
import_cluster(
    name="生产环境",
    kubeconfig="/path/to/kubeconfig.yaml",
    namespace="default",
    is_default=True
)

# 批量列出 Pod（自动使用默认集群和命名空间）
batch_list_resources(resource_types="pods", namespace="default")

# 查看集群信息
get_cluster_info()

# 检查集群健康状态
check_cluster_health()

# 批量创建资源（含 Deployment）
batch_create_resources(resources="[{...}]", namespace="default")

# 查看所有集群
list_clusters()

# 切换默认集群
set_default_cluster(name="测试环境")

# 测试集群连接
test_cluster_connection(name="生产环境")

# 1. 启动服务（启用认证）
MCP_AUTH_ENABLED=true MCP_JWT_SECRET=your-secret-key \
  k8s-mcp-server --transport streamable --host 0.0.0.0 --port 8000

# 2. 生成管理员 Token
MCP_JWT_SECRET=your-secret-key mcp-admin bootstrap
# 输出：MCP_BOOTSTRAP_ADMIN_JWT=eyJhbGci...

# 3. 为用户签发 Token
MCP_JWT_SECRET=your-secret-key mcp-admin issue --user alice --expires 7776000

# 4. 通过 MCP Tool 为用户分配集群权限（管理员在 MCP 对话中执行）
# admin_manage_users(action="grant_access", user_id="alice",
#   cluster_name="prod", namespace="default", profile="developer")

{
  "mcpServers": {
    "k8s-mcp-server": {
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGci..."
      }
    }
  }
}

mcp-admin bootstrap          # 生成管理员 Token
mcp-admin issue --user bob   # 签发用户 Token
mcp-admin extend --jti xxx --expires 7776000      # 延期单个 token（token 字符串不变；user_id == 'admin' 不可延期）
mcp-admin extend --user bob --expires 7776000     # 延期该用户最近的一个 token
mcp-admin migrate-extensions [--dry-run]         # 把 user_grants.json 里 active grant 迁入延期表（排除 user_id == 'admin'，幂等）
                                                 # 启动时仅在 token_extensions.json 不存在时自动迁移一次；后续新增用户需运行 --overwrite 补齐
mcp-admin revoke --jti xxx   # 撤销单个 Token
mcp-admin revoke-user --user bob  # 撤销用户全部 Token
mcp-admin list-users         # 列出所有用户（含 extended_tokens 计数）
mcp-admin grant --user bob --cluster prod --namespace default --profile developer  # 分配权限
mcp-admin revoke-access --user bob --cluster prod --namespace default  # 撤销权限
mcp-admin list-profiles      # 列出所有 Profile

# 构建并部署到 Kubernetes
docker build -t k8s-mcp-server:latest .
kubectl apply -f k8s/

# 查看部署状态
kubectl get pods -l app=k8s-mcp-server
kubectl logs -f deployment/k8s-mcp-server

# 运行全部回归测试（需可用的 K8s 集群）
python -m tests.regression_test

# 仅运行同步测试（无需集群）
REGRESSION_SKIP_ASYNC=1 python -m tests.regression_test