Troubleshoot MCP Server

Kubernetes支持的MCP服务器软件包

一个模型上下文协议（MCP）服务器，用于人工智能模型与Kubernetes支持包进行交互。该服务器使人工智能模型能够通过探索由（系统）生成的支持包来分析和排查Kubernetes集群的问题 故障排除 工具。

特点/功能

• 🚀 包管理初始化并管理 Kubernetes 支持包
• 🎮 表示游戏（Game）的符号，常用于网络交流中表达与游戏相关的内容或情绪。 命令执行针对软件包的API服务器运行kubectl命令
• 📁 代表文件夹的图标，可翻译为“文件夹”。 文件资源管理器在软件包内导航和搜索文件
• 🔐 安全认证基于令牌的包访问认证
• 🐳 这个表情符号通常表示一只哭泣的鲸鱼，可以翻译为“哭泣的鲸鱼”或根据语境简化为“鲸鱼哭脸”。在中文网络交流中，它常被用来表达悲伤、委屈或无奈的情绪。 集装箱支撑作为容器化应用程序运行
• ⚡（闪电符号，无具体文字含义，可表示快速、能量、电等概念） 单捆模式无状态操作，适用于临时/无服务器部署

单包模式（无状态操作）

对于无状态/临时部署（临时工作流、无服务器函数、按请求分配容器的架构），启用 单捆绑模式：

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

什么是单捆绑模式？

单包模式通过将磁盘上包的存在视为真实来源，消除了内存中对包状态的跟踪。这实现了：

• 自动恢复程序包当服务器启动时，它会自动激活保存在磁盘上的插件包
• 无状态服务器重启每次服务器重启时，都会自动使用已持久化的包，而无需重新初始化
• 单包不变性一次只能存在一个数据包，以避免状态混乱
• 无缝时间/无服务器集成与短生命周期的服务器实例完美配合

使用模式

# 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")

何时使用单捆绑模式

✅ 使用时机：

• 在时间工作流中运行，其中每个活动都会启动一个新的服务器
• 在无服务器/lambda环境中部署具有短期生命周期的函数
• 使用每请求容器架构
• 服务器实例经常重启

❌（这个符号在中文中通常表示“错误”或“取消”，但具体含义可能根据上下文有所不同） 请勿在以下情况下使用：

• 你需要同时处理多个数据包
• 运行长期存活的服务器实例（默认模式即可）
• 绑定状态可以在内存中保持

配置详情

| temp dir | 持久化包存储目录 |注 PRESERVE_BUNDLES=true :

必须设置为单包模式，以确保包在服务器重启后仍然存在。

快速入门

使用 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： 查看 Podman 文档

以获取全面的容器配置详情。

1. 手动安装
2. 确保已安装 Python 3.13

# 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

1. 设置包含紫外线的环境（推荐）：

export SBCTL_TOKEN=your-token

1. 设置您的身份验证令牌：

uv run python -m troubleshoot_mcp_server

使用UV运行服务器：

容器镜像变体

此项目提供了两种不同的容器镜像版本： troubleshoot-mcp-server-dev:latest

• 发展形象：目的
• 本地开发和测试由……建造/建成 ./scripts/build.sh ：
• （默认）用法
• 当从源代码构建或在本地进行开发时示例

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

： troubleshoot-mcp-server:latest

• 生产图像：目的
• 官方发布和生产部署由……建造/建成 IMAGE_NAME=troubleshoot-mcp-server ./scripts/build.sh
• 带有（某种工具/技术的）CI/CD（持续集成/持续交付）流水线使用方法
• 在生产环境中或使用官方发布版本时示例

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

：

为何有两个变体？ -dev 该

• 后缀可防止本地开发镜像与官方生产发布版本之间的冲突。这使用户能够：
• 使用官方容器发布版本，避免本地构建的干扰
• 在本地开发和测试，避免覆盖生产环境镜像

保持开发环境和生产环境之间的清晰分离

文档

• 如需查看完整文档，请参阅：用户指南
• 安装、配置和使用说明API 参考文档
• 详细API文档开发者指南
• 开发者信息Podman 指南
• 容器设置与配置系统架构
• 整体系统设计故障排除指南
• 常见问题的解决方案发布流程

如何创建新版本 这个（或“它”） 例子

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

工具

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

• initialize_bundle包管理

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

• kubectlKubectl 命令

对软件包执行 kubectl 命令

• list_files文件操作
• read_file列出文件和目录
• grep_files读取文件内容

在文件中搜索模式

示例用法

// 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```"
}

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

├── 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]"

为了开发，以可编辑模式安装包含开发依赖项的包： 如需关于依赖管理的详细指南，请参阅我们的依赖管理指南

。

代码风格

# Format code with Ruff
uv run ruff format .

# Lint code with Ruff
uv run ruff check .

代码格式化是使用 Ruff 完成的：

# 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

测试

• 要求
• kubectl Python 3.13
• sbctl 命令行工具
• 用于包管理的命令行工具 SBCTL_TOKEN 用于身份验证的令牌（设置为 REPLICATED 或者

环境变量)

所有依赖项均包含在Podman容器中，因此这是推荐的部署方法。

做出贡献 欢迎投稿！请参阅 开发者指南

关于如何参与的详细信息。

许可证 这个项目采用Apache License 2.0授权——详见 许可证