README - MCP Server for Kubernetes Support Bundles by chris-sanders

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
🐳 Container Support: Run as a containerized application

Quick Start

Using Podman

The easiest way to get started is using Podman:

# Build the image
podman build -t mcp-server-troubleshoot:latest -f Containerfile .

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

See the for comprehensive container configuration details.

Manual Installation

Ensure you have Python 3.13 installed
Set up 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
uv pip install -e ".[dev]"  # For development with testing tools

Set up your authentication token:

export SBCTL_TOKEN=your-token

Run the server using UV:

uv run python -m mcp_server_troubleshoot

Documentation

For comprehensive documentation, see:

: Installation, configuration, and usage instructions
: Detailed API documentation
: Information for developers
: Container setup and configuration
: Overall system design
: Solutions for common issues
: How to create new releases

The 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
│   ├── 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
│   └── 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

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

For detailed guidance on dependency management, see our .

Code Style

Code formatting is done using Black and Ruff:

# Format code with Black
uv run black .

# Lint code with Ruff
uv run ruff check .

Testing

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

Requirements

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

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

Contributing

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

License

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