MCP Server for Kubernetes Support Bundles

Kubernetes 支持包 MCP 服务

一个供 AI 模型与 Kubernetes 支持包交互的 Model Context Protocol（MCP）服务。此服务让 AI 模型能够通过探索 Troubleshoot 工具生成的支持包，分析并排查 Kubernetes 集群问题。

功能

• 🚀 支持包管理：初始化和管理 Kubernetes 支持包
• 🎮 命令执行：针对支持包的 API 服务器运行 kubectl 命令
• 📁 文件浏览器：浏览和搜索支持包中的文件
• 🔐 安全认证：使用基于令牌的认证访问支持包
• 🐳 容器支持：作为容器化应用运行
• ⚡ 单支持包模式：为临时／无服务器部署提供无状态运行

单支持包模式（无状态运行）

对于无状态／临时部署（Temporal 工作流、无服务器函数、每个请求一个容器的架构），请启用 单支持包模式：

export MCP_SINGLE_BUNDLE_MODE=true
export PRESERVE_BUNDLES=true
export MCP_BUNDLE_STORAGE=/persistent-storage/bundles

什么是单支持包模式？

单支持包模式不再在内存中跟踪支持包状态，而是将磁盘上是否存在支持包作为事实来源。这使得：

• 自动恢复支持包：服务启动时，会自动激活持久化在磁盘上的支持包
• 无状态服务重启：每次重启服务时，都会自动使用已持久化的支持包，无需重新初始化
• 单支持包约束：同一时间只能存在一个支持包，避免状态混乱
• 与 Temporal／无服务器环境无缝集成：非常适用于生命周期较短的服务实例

使用模式

# Activity 1: Initialize bundle
# Server starts → downloads bundle → exits
initialize_bundle(url="https://example.com/bundle.tar.gz")

# Activity 2: Use bundle (new server instance)
# Server starts → auto-activates bundle from disk → succeeds
list_files(path="/kubernetes/pods")

# Activity 3: Run kubectl (another new server instance)
# Server starts → auto-activates bundle → succeeds
kubectl(command="get pods")

何时使用单支持包模式

✅ 适用于：

• 在每个活动都会启动新服务的 Temporal 工作流中运行
• 部署到使用短生命周期函数的无服务器／lambda 环境
• 使用每个请求一个容器的架构
• 服务实例频繁重启

❌ 不适用于：

• 需要同时处理多个支持包
• 运行长期服务实例（默认模式即可正常工作）
• 可在内存中维护支持包状态

配置详情

环境变量	默认值	描述
MCP_SINGLE_BUNDLE_MODE	false	启用单支持包模式
PRESERVE_BUNDLES	false	清理后仍将支持包文件保留在磁盘上
MCP_BUNDLE_STORAGE	temp dir	用于持久化存储支持包的目录

注意：必须在单支持包模式下设置 PRESERVE_BUNDLES=true，以确保支持包在服务重启后仍然保留。

快速开始

使用 Podman

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

# Build the image (uses melange/apko instead of Containerfile)
./scripts/build.sh

# Run the server
podman run -i --rm \
  -v "/path/to/bundles:/data/bundles" \
  -e SBCTL_TOKEN="your-token" \
  troubleshoot-mcp-server-dev:latest

有关容器配置的完整详情，请参阅 Podman 文档。

手动安装

1. 确保已安装 Python 3.13
2. 使用 UV 设置环境（推荐）：

# Automatically creates and sets up environment with best available Python
./scripts/setup_env.sh

# OR create manually with UV
uv venv -p python3.13 .venv
uv pip install -e ".[dev]"  # For development with testing tools

3. 设置认证令牌：

export SBCTL_TOKEN=your-token

4. 使用 UV 运行服务：

uv run python -m troubleshoot_mcp_server

容器镜像变体

此项目提供两种不同的容器镜像变体：

开发镜像：troubleshoot-mcp-server-dev:latest

• 用途：本地开发和测试
• 构建方式：./scripts/build.sh（默认）
• 用法：从源代码构建或进行本地开发时使用
• 示例：

  ./scripts/build.sh
  podman run -i --rm troubleshoot-mcp-server-dev:latest
  

生产镜像：troubleshoot-mcp-server:latest

• 用途：官方发布和生产部署
• 构建方式：CI/CD 流水线使用 IMAGE_NAME=troubleshoot-mcp-server ./scripts/build.sh
• 用法：在生产环境中或使用官方发布版本时使用
• 示例：

  IMAGE_NAME=troubleshoot-mcp-server ./scripts/build.sh
  podman run -i --rm troubleshoot-mcp-server:latest
  

为什么有两个变体？

-dev 后缀可避免本地开发镜像与官方生产版本发生冲突。这样用户可以：

• 使用官方容器版本，而不受本地构建影响
• 在本地开发和测试，而不会覆盖生产镜像
• 明确区分开发环境和生产环境

文档

如需完整文档，请参阅：

• 用户指南：安装、配置和使用说明
• API 参考：详细的 API 文档
• 开发者指南：面向开发者的信息
• Podman 指南：容器设置和配置
• 系统架构：整体系统设计
• 故障排查指南：常见问题的解决方案
• 发布流程：如何创建新版本

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

工具

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

Bundle 管理

• initialize_bundle：初始化一个支持包以供使用

Kubectl 命令

• kubectl：对支持包执行 kubectl 命令

文件操作

• list_files：列出文件和目录
• read_file：读取文件内容
• grep_files：在文件中搜索模式

使用示例

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

// Request to list files
{
  "name": "list_files",
  "input": {
    "path": "/kubernetes/pods",
    "recursive": false
  }
}

// Response (simplified)
{
  "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/                      # Documentation
│   ├── CLAUDE.md              # AI assistant instructions
│   ├── PODMAN.md              # Podman configuration guide
│   ├── README.md              # Project overview (this file)
│   ├── docs/                  # Detailed documentation
│   │   ├── agentic/           # AI agent documentation
│   │   ├── components/        # Component design docs
│   │   └── examples/          # Example prompts and usage
│   └── tasks/                 # Development tasks
│       ├── completed/         # Completed tasks
│       ├── started/           # Tasks in progress
│       └── ready/             # Tasks ready to implement
├── examples/                  # Example configurations (for reference only)
│   └── mcp-servers/           # MCP server example configs
├── scripts/                   # Utility scripts
│   ├── build.sh               # Podman build script
│   └── run.sh                 # Podman run script
├── src/                       # Source code
│   └── troubleshoot_mcp_server/
│       ├── __init__.py
│       ├── __main__.py        # Entry point
│       ├── bundle.py          # Bundle management
│       ├── cli.py             # CLI interface
│       ├── config.py          # Configuration management
│       ├── files.py           # File operations
│       ├── kubectl.py         # Kubectl command execution
│       ├── lifecycle.py       # Bundle lifecycle management
│       └── server.py          # MCP server implementation
└── tests/                     # Test files
    ├── e2e/                   # End-to-end tests
    ├── fixtures/              # Test fixtures
    ├── functional/            # Functional tests (MCP protocol validation)
    ├── integration/           # Integration tests
    ├── unit/                  # Unit tests
    └── util/                  # Test utilities

开发

安装

进行开发时，请以可编辑模式安装软件包及开发依赖：

# Clone the repository
git clone https://github.com/your-username/troubleshoot-mcp-server.git
cd troubleshoot-mcp-server

# Set up the development environment using UV
./scripts/setup_env.sh

# Or manually with UV
uv venv -p python3.13 .venv
uv pip install -e ".[dev]"

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

代码风格

使用 Ruff 格式化代码：

# Format code with Ruff
uv run ruff format .

# Lint code with Ruff
uv run ruff check .

测试

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run a specific test type using markers
uv run pytest -m unit
uv run pytest -m integration
uv run pytest -m functional  # MCP protocol validation
uv run pytest -m e2e

# Run tests with detailed warnings
uv run pytest -W all

# Run tests with warnings as errors
uv run pytest -W error

# Or use the helper script
./scripts/run_tests.sh unit
./scripts/run_tests.sh integration

要求

• Python 3.13
• kubectl 命令行工具
• 用于 Bundle 管理的 sbctl 命令行工具
• 用于身份验证的令牌（设置为 SBCTL_TOKEN 或 REPLICATED 环境变量）

所有依赖项都包含在 Podman 容器中，因此推荐使用这种部署方式。

贡献

欢迎贡献！有关如何参与贡献的详情，请参阅开发者指南。

许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。