MCP 服务器

MCP Server for Kubernetes Support Bundles

chris-sanders

开发者工具

访问服务器

README

用于 Kubernetes 支持包的 MCP 服务器

一个模型上下文协议 (MCP) 服务器，供 AI 模型与 Kubernetes 支持包交互。该服务器使 AI 模型能够通过探索由 Troubleshoot 工具生成的支持包来分析和排除 Kubernetes 集群的故障。

特性

🚀 包管理: 初始化和管理 Kubernetes 支持包
🎮 命令执行: 针对包的 API 服务器运行 kubectl 命令
📁 文件浏览器: 导航和搜索包中的文件
🔐 安全认证: 基于令牌的包访问认证
🐳 Docker 支持: 作为容器化应用程序运行

快速开始

使用 Docker

最简单的入门方式是使用 Docker：

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

# 运行服务器
docker run -i --rm \
  -v "/path/to/bundles:/data/bundles" \
  -e SBCTL_TOKEN="your-token" \
  mcp-server-troubleshoot:latest

有关全面的容器配置详细信息，请参阅 Docker 文档。

手动安装

确保已安装 Python 3.13
使用 UV 创建虚拟环境（推荐）：

# 自动创建并设置具有最佳可用 Python 的环境
./scripts/setup_env.sh

# 或者使用 UV 手动创建
uv venv -p python3.13 .venv
source .venv/bin/activate

安装软件包：

# 使用 uv
uv pip install -e ".[dev]"  # 用于使用测试工具进行开发

设置您的身份验证令牌：

export SBCTL_TOKEN=your-token

运行服务器：

python -m mcp_server_troubleshoot

文档

有关全面的文档，请参阅：

用户指南：安装、配置和使用说明
API 参考：详细的 API 文档
开发者指南：面向开发者的信息
Docker 指南：容器设置和配置
系统架构：整体系统设计
故障排除指南：常见问题的解决方案

examples 目录包含开发人员的参考配置。这些文件不应修改。

工具

MCP 服务器为 AI 模型提供以下工具：

包管理

initialize_bundle: 初始化支持包以供使用

Kubectl 命令

kubectl: 针对包执行 kubectl 命令

文件操作

list_files: 列出文件和目录
read_file: 读取文件内容
grep_files: 搜索文件中的模式

使用示例

AI 模型可以使用 MCP 协议与服务器交互：

// 请求列出文件
{
  "name": "list_files",
  "input": {
    "path": "/kubernetes/pods",
    "recursive": false
  }
}

// 响应（简化）
{
  "content": "Listed files in /kubernetes/pods non-recursively:\n```json\n[\n  {\n    \"name\": \"kube-system\",\n    \"path\": \"/kubernetes/pods/kube-system\",\n    \"type\": \"directory\",\n    \"size\": null,\n    \"modified\": \"2025-04-10T12:30:45Z\"\n  },\n  {\n    \"name\": \"pod-definition.yaml\",\n    \"path\": \"/kubernetes/pods/pod-definition.yaml\",\n    \"type\": \"file\",\n    \"size\": 1254,\n    \"modified\": \"2025-04-10T12:30:45Z\"\n  }\n]\n```\nDirectory metadata:\n```json\n{\n  \"path\": \"/kubernetes/pods\",\n  \"recursive\": false,\n  \"total_files\": 1,\n  \"total_dirs\": 1\n}\n```"
}

项目结构

├── docs/                      # 文档
│   ├── CLAUDE.md              # AI 助手说明
│   ├── DOCKER.md              # Docker 配置指南
│   ├── README.md              # 项目概述（此文件）
│   ├── docs/                  # 详细文档
│   │   ├── agentic/           # AI 代理文档
│   │   ├── components/        # 组件设计文档
│   │   └── examples/          # 示例提示和用法
│   └── tasks/                 # 开发任务
│       ├── completed/         # 已完成的任务
│       ├── started/           # 正在进行的任务
│       └── ready/             # 准备实施的任务
├── examples/                  # 示例配置（仅供参考）
│   └── mcp-servers/           # MCP 服务器示例配置
├── scripts/                   # 实用程序脚本
│   ├── build.sh               # Docker 构建脚本
│   └── run.sh                 # Docker 运行脚本
├── src/                       # 源代码
│   └── mcp_server_troubleshoot/
│       ├── __init__.py
│       ├── __main__.py        # 入口点
│       ├── bundle.py          # 包管理
│       ├── cli.py             # CLI 接口
│       ├── config.py          # 配置管理
│       ├── files.py           # 文件操作
│       ├── kubectl.py         # Kubectl 命令执行
│       ├── lifecycle.py       # 包生命周期管理
│       └── server.py          # MCP 服务器实现
└── tests/                     # 测试文件
    ├── e2e/                   # 端到端测试
    ├── fixtures/              # 测试夹具
    ├── integration/           # 集成测试
    ├── unit/                  # 单元测试
    └── util/                  # 测试实用程序

开发

安装

对于开发，请以可编辑模式安装具有开发依赖项的软件包：

# 克隆存储库
git clone https://github.com/your-username/mcp-server-troubleshoot.git
cd mcp-server-troubleshoot

# 创建一个虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装开发依赖项
uv pip install -e ".[dev]"

有关依赖项管理的详细指导，请参阅我们的依赖项管理指南。

代码风格

代码格式化使用 Black 和 Ruff 完成：

# 使用 Black 格式化代码
black .

# 使用 Ruff 检查代码
ruff check .

测试

# 运行所有测试
pytest

# 运行详细输出
pytest -v

# 使用标记运行特定测试类型
pytest -m unit
pytest -m integration
pytest -m e2e

# 运行带有详细警告的测试
pytest -W all

# 运行带有警告作为错误的测试
pytest -W error