MCP Server for Kubernetes Support Bundles

A Model Context Protocol (MCP) server for AI models to interact with Kubernetes support bundles. This server enables AI models to analyze and troubleshoot Kubernetes clusters by exploring support bundles generated by the Troubleshoot tool.

Features

• 🚀 Bundle Management: Initialize and manage Kubernetes support bundles
• 🎮 Command Execution: Run kubectl commands against bundle's API server
• 📁 File Explorer: Navigate and search files within the bundle
• 🔐 Secure Authentication: Token-based authentication for bundle access
• 🐳 Docker Support: Run as a containerized application

Quick Start

Using Docker

The easiest way to get started is using Docker:

# Build the image
docker build -t mcp-server-troubleshoot:latest .

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

See the Docker documentation for comprehensive container configuration details.

Manual Installation

1. Ensure you have Python 3.13 installed
2. Create a virtual environment with UV (recommended):

# 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
source .venv/bin/activate

3. Install the package:

# Using uv
uv pip install -e ".[dev]"  # For development with testing tools

3. Set up your authentication token:

export SBCTL_TOKEN=your-token

4. Run the server:

python -m mcp_server_troubleshoot

Documentation

For comprehensive documentation, see:

• User Guide: Installation, configuration, and usage instructions
• API Reference: Detailed API documentation
• Developer Guide: Information for developers
• Docker Guide: Container setup and configuration
• System Architecture: Overall system design
• Troubleshooting Guide: Solutions for common issues

The examples directory contains reference configurations for developers. These files should not be modified.

Tools

The MCP server provides the following tools for AI models:

Bundle Management

• initialize_bundle: Initialize a support bundle for use

Kubectl Commands

• kubectl: Execute kubectl commands against the bundle

File Operations

• list_files: List files and directories
• read_file: Read file contents
• grep_files: Search for patterns in files

Example Usage

AI models can interact with the server using the MCP protocol:

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

Project Structure

├── docs/                      # Documentation
│   ├── CLAUDE.md              # AI assistant instructions
│   ├── DOCKER.md              # Docker 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               # Docker build script
│   └── run.sh                 # Docker run script
├── src/                       # Source code
│   └── mcp_server_troubleshoot/
│       ├── __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 
    ├── integration/           # Integration tests
    ├── unit/                  # Unit tests
    └── util/                  # Test utilities

Development

Installation

For development, install the package in editable mode with development dependencies:

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

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with development dependencies
uv pip install -e ".[dev]"

For detailed guidance on dependency management, see our Dependency Management Guide.

Code Style

Code formatting is done using Black and Ruff:

# Format code with Black
black .

# Lint code with Ruff
ruff check .

Testing

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run a specific test type using markers
pytest -m unit
pytest -m integration
pytest -m e2e

# Run tests with detailed warnings
pytest -W all

# Run tests with warnings as errors
pytest -W error

Requirements

• Python 3.13
• kubectl command-line tool
• sbctl command-line tool for bundle management
• Token for authentication (set as SBCTL_TOKEN environment variable)

All dependencies are included in the Docker container, making it the recommended deployment method.

Contributing

Contributions are welcome! Please see the Developer Guide for details on how to contribute.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.