troubleshoot-mcp-server 1.15.1
MCP server for Kubernetes support bundles
Requires Python: >=3.13
Keywords: mcp, kubernetes, troubleshoot, support-bundle, ai, claude, debugging

# MCP Server for Kubernetes Support Bundles

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python Version](https://img.shields.io/badge/python-3.13-blue)](https://www.python.org/downloads/)

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](https://troubleshoot.sh/) 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
- ⚡ **Single Bundle Mode**: Stateless operation for ephemeral/serverless deployments

## Single Bundle Mode (Stateless Operation)

For stateless/ephemeral deployments (Temporal workflows, serverless functions, container-per-request architectures), enable **Single Bundle Mode**:

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

### What is Single Bundle Mode?

Single Bundle Mode eliminates in-memory bundle state tracking by treating the presence of a bundle on disk as the source of truth. This enables:

- **Automatic Bundle Restoration**: When the server starts, it auto-activates the bundle persisted on disk
- **Stateless Server Restarts**: Each server restart automatically uses the persisted bundle without re-initialization
- **Single Bundle Invariant**: Only one bundle can exist at a time, preventing state confusion
- **Seamless Temporal/Serverless Integration**: Works perfectly with short-lived server instances

### Usage Pattern

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

### When to Use Single Bundle Mode

✅ **Use when:**
- Running in Temporal workflows where each activity spawns a new server
- Deploying to serverless/lambda environments with short-lived functions
- Using container-per-request architectures
- Server instances are frequently restarted

❌ **Don't use when:**
- You need to work with multiple bundles simultaneously
- Running long-lived server instances (default mode works fine)
- Bundle state can be maintained in memory

### Configuration Details

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `MCP_SINGLE_BUNDLE_MODE` | `false` | Enable single bundle mode |
| `PRESERVE_BUNDLES` | `false` | Keep bundle files on disk after cleanup |
| `MCP_BUNDLE_STORAGE` | temp dir | Directory for persistent bundle storage |

**Note**: `PRESERVE_BUNDLES=true` must be set with single bundle mode to ensure bundles persist across server restarts.

## Quick Start

### Using Podman

The easiest way to get started is using Podman:

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

See the [Podman documentation](PODMAN.md) for comprehensive container configuration details.

### Manual Installation

1. Ensure you have Python 3.13 installed
2. Set up environment with UV (recommended):

```bash
# 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. Set up your authentication token:

```bash
export SBCTL_TOKEN=your-token
```

4. Run the server using UV:

```bash
uv run python -m troubleshoot_mcp_server
```

## Container Image Variants

This project provides two distinct container image variants:

### Development Image: `troubleshoot-mcp-server-dev:latest`
- **Purpose**: Local development and testing
- **Built by**: `./scripts/build.sh` (default)
- **Usage**: When building from source or developing locally
- **Example**: 
  ```bash
  ./scripts/build.sh
  podman run -i --rm troubleshoot-mcp-server-dev:latest
  ```

### Production Image: `troubleshoot-mcp-server:latest`
- **Purpose**: Official releases and production deployments
- **Built by**: CI/CD pipeline with `IMAGE_NAME=troubleshoot-mcp-server ./scripts/build.sh`
- **Usage**: In production environments or when using official releases
- **Example**:
  ```bash
  IMAGE_NAME=troubleshoot-mcp-server ./scripts/build.sh
  podman run -i --rm troubleshoot-mcp-server:latest
  ```

### Why Two Variants?

The `-dev` suffix prevents conflicts between local development images and official production releases. This allows users to:
- Use official container releases without interference from local builds
- Develop and test locally without overwriting production images
- Maintain clear separation between development and production environments

## Documentation

For comprehensive documentation, see:

- [User Guide](docs/user_guide.md): Installation, configuration, and usage instructions
- [API Reference](docs/api_reference.md): Detailed API documentation
- [Developer Guide](docs/developer_guide.md): Information for developers
- [Podman Guide](PODMAN.md): Container setup and configuration
- [System Architecture](docs/architecture.md): Overall system design
- [Troubleshooting Guide](docs/troubleshooting.md): Solutions for common issues
- [Release Process](RELEASE.md): How to create new releases

The [examples](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:

```json
// 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
│   └── 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
```

## Development

### Installation

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

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

For detailed guidance on dependency management, see our [Dependency Management Guide](docs/development/dependency_management.md).

### Code Style

Code formatting is done using Ruff:

```bash
# Format code with Ruff
uv run ruff format .

# Lint code with Ruff
uv run ruff check .
```

### Testing

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

## 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 [Developer Guide](docs/developer_guide.md) for details on how to contribute.

## License

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