troubleshoot-mcp-server

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
• ⚡ 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:

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

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

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

  ./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:

  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: Installation, configuration, and usage instructions
• API Reference: Detailed API documentation
• Developer Guide: Information for developers
• Podman Guide: Container setup and configuration
• System Architecture: Overall system design
• Troubleshooting Guide: Solutions for common issues
• Release Process: How to create new releases

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
│   ├── 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:

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

Code Style

Code formatting is done using Ruff:

# Format code with Ruff
uv run ruff format .

# 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 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 for details on how to contribute.

License

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