Merge pull request #80 from tongtie/feat-k8s-mcp-server

feat: k8s mcp server

Author: zhouhaoUCAS

mcp_servers/kubernetes_mcp_server/.env.example

@@ -0,0 +1,57 @@
+DEFAULT_LLM_API_KEY=""
+DEFAULT_LLM_BASE_URL=""
+DEFAULT_LLM_MODEL_NAME=""
+
+# ================================
+# Kubernetes MCP 基础配置
+# ================================
+
+# MCP 传输模式: stdio, sse, streamable-http
+K8S_MCP_TRANSPORT=stdio
+
+# 启用的工具集: config,core,helm (逗号分隔)
+K8S_MCP_TOOLSETS=config,core,helm
+
+# 安全模式配置
+K8S_MCP_READ_ONLY=false
+K8S_MCP_DISABLE_DESTRUCTIVE=false
+
+# SSE/Streamable HTTP 模式端口 (仅网络模式需要)
+K8S_MCP_PORT=8000
+
+# ================================
+# 单集群配置
+# ================================
+
+# kubeconfig 文件路径 (可选，默认使用 ~/.kube/config)
+KUBECONFIG=~/.kube/config
+
+
+# ================================
+# 调试配置 (可选)
+# ================================
+
+# 启用调试日志
+DEBUG=0
+
+# Python 路径 (通常不需要修改)
+PYTHONPATH=.
+
+# ================================
+# 使用说明
+# ================================
+
+# 1. 基础使用 (kubernetes_demo.py):
+#    - 设置 LLM 配置
+#    - 设置 KUBECONFIG 
+#    - 运行: python examples/mcp_tools/kubernetes_demo.py
+
+
+# ================================
+# 安全提醒
+# ================================
+
+# - 生产环境建议使用 K8S_MCP_READ_ONLY=true
+# - 敏感环境建议使用 K8S_MCP_DISABLE_DESTRUCTIVE=true
+# - 确保 kubeconfig 文件权限设置正确 (600)
+# - 定期轮换 API 密钥和访问凭证

mcp_servers/kubernetes_mcp_server/README.md

@@ -0,0 +1,101 @@
+# Kubernetes MCP 服务器
+
+## 概述
+
+Kubernetes MCP 服务器为 OxyGent 提供完整的 Kubernetes 集群管理功能，支持配置管理、核心资源操作和 Helm 模板化部署。
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+pip install -r mcp_servers/kubernetes_mcp_server/requirements.txt
+```
+
+### 2. 设置环境变量
+
+注： 无K8S环境时，可以通过k8s `kind`在本地快速启动: https://kind.sigs.k8s.io/
+
+```bash
+# 备份本地环境变量
+cp .env .env.bak
+
+# 使用本mcp的环境变量文件
+cp mcp_servers/kubernetes_mcp_server/.env.example .env
+```
+
+### 3. 基础使用
+
+```bash
+
+# 启动服务器 (stdio 模式)
+python -m mcp_servers.kubernetes_mcp_server.server --transport stdio
+
+# 在 OxyGent 中使用
+python mcp_servers/kubernetes_mcp_server/kubernetes_demo.py
+```
+
+## 功能特性
+
+### 🔧 配置工具集 (config)
+- 查看 kubeconfig 配置和上下文
+- 列出所有可用的集群上下文
+- 切换当前上下文
+
+### 🚀 核心工具集 (core)
+- **Pods**: 列出、查看、获取日志、执行命令
+- **Nodes**: 查看节点状态和资源使用
+- **Namespaces**: 管理命名空间
+- **Resources**: 通用资源操作
+- **Events**: 查看集群事件
+
+### ⚙️ Helm 工具集 (helm)
+- 使用 Jinja2 模板渲染 Helm 风格配置
+- 部署和卸载应用
+- 无需 Helm 二进制依赖
+
+## 使用示例
+
+### 基础集群管理
+```python
+# 完整功能示例
+python examples/mcp_tools/kubernetes_demo.py
+```
+
+
+## 配置选项
+
+### 环境变量
+- `K8S_MCP_TRANSPORT`: 传输模式 (stdio/sse/streamable-http)
+- `K8S_MCP_TOOLSETS`: 启用的工具集 (config,core,helm)
+- `K8S_MCP_READ_ONLY`: 只读模式
+- `K8S_MCP_DISABLE_DESTRUCTIVE`: 禁用破坏性操作
+- `KUBECONFIG`: kubeconfig 文件路径
+
+### 命令行参数
+```bash
+python -m mcp_servers.kubernetes_mcp_server.server \
+  --transport stdio \
+  --toolsets config,core,helm \
+  --read-only \
+  --disable-destructive
+```
+
+## 安全模式
+
+### 只读模式
+```bash
+--read-only
+```
+- 禁用所有写操作
+- 仅支持查看和监控
+- 适合生产环境
+
+### 禁用破坏性操作
+```bash
+--disable-destructive
+```
+- 保留创建和更新
+- 禁用删除操作
+- 适合测试环境
+

mcp_servers/kubernetes_mcp_server/__init__.py

@@ -0,0 +1,57 @@
+"""
+Kubernetes MCP Server package initializer.
+
+提供:
+- 全局 FastMCP 实例 (用于在各工具模块上通过 @mcp.tool 装饰器统一注册)
+- 非破坏模式与禁删/禁更新等安全开关的环境变量读取
+- 其他子模块将通过 `from . import mcp` 共享同一个 MCP 实例
+"""
+
+from __future__ import annotations
+
+import os
+from mcp.server.fastmcp import FastMCP
+
+# 全局 MCP 实例：各工具模块通过 `from . import mcp` 引用此实例并注册工具
+# 运行传输模式由启动入口 server.py 控制 (stdio / sse / streamable-http)
+mcp = FastMCP()
+
+# 安全与变更开关（环境变量控制）
+# - K8S_MCP_READ_ONLY=true: 仅允许只读/非破坏工具
+# - K8S_MCP_DISABLE_DESTRUCTIVE=true: 禁止 destructive 类操作（delete / update 等）
+#   注意：这两个开关的生效逻辑由 server.py 的工具过滤器与具体工具内部的保护共同保证
+_READ_ONLY = os.getenv("K8S_MCP_READ_ONLY", "").strip().lower() in {
+    "1",
+    "true",
+    "yes",
+    "on",
+}
+_DISABLE_DESTRUCTIVE = os.getenv("K8S_MCP_DISABLE_DESTRUCTIVE", "").strip().lower() in {
+    "1",
+    "true",
+    "yes",
+    "on",
+}
+
+
+def is_read_only() -> bool:
+    """
+    返回是否启用只读模式（READ-ONLY）。
+    该模式通常会移除 delete/update 等破坏性工具，仅保留只读与创建/更新安全工具的最小集合。
+    """
+    return _READ_ONLY
+
+
+def is_disable_destructive() -> bool:
+    """
+    返回是否禁用破坏性操作（DELETE/UPDATE 等）。
+    在 READ-ONLY 未开启时，也可通过该开关细粒度限制工具集合。
+    """
+    return _DISABLE_DESTRUCTIVE
+
+
+__all__ = [
+    "mcp",
+    "is_read_only",
+    "is_disable_destructive",
+]