MCP Server for Kubernetes Support Bundles

Kubernetes サポートバンドル用 MCP サーバー

Kubernetes のサポートバンドルを AI モデルが操作するための Model Context Protocol（MCP）サーバーです。このサーバーを使用すると、Troubleshoot ツールで生成されたサポートバンドルを調べて、AI モデルが Kubernetes クラスターを分析し、トラブルシューティングを行えます。

特長

• 🚀 バンドル管理：Kubernetes サポートバンドルを初期化して管理します
• 🎮 コマンド実行：バンドルの API サーバーに対して kubectl コマンドを実行します
• 📁 ファイルエクスプローラー：バンドル内のファイルを参照、検索します
• 🔐 安全な認証：バンドルへのアクセスにトークンベースの認証を使用します
• 🐳 コンテナー対応：コンテナー化されたアプリケーションとして実行できます
• ⚡ 単一バンドルモード：一時的なデプロイやサーバーレスのデプロイ向けに、ステートレスで動作します

単一バンドルモード（ステートレス動作）

Temporal ワークフロー、サーバーレス関数、リクエストごとにコンテナーを使用するアーキテクチャなど、ステートレスまたは一時的なデプロイでは、単一バンドルモードを有効にします。

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

単一バンドルモードとは？

単一バンドルモードでは、ディスク上にバンドルが存在することを信頼できる情報源として扱うことで、メモリー内のバンドル状態の追跡をなくします。これにより、次のことが可能になります。

• バンドルの自動復元：サーバーの起動時に、ディスクに保存されたバンドルを自動的に有効化します
• ステートレスなサーバー再起動：サーバーを再起動するたびに、再初期化せずに保存済みのバンドルを自動的に使用します
• 単一バンドルの不変条件：同時に存在できるバンドルを1つに制限し、状態の混乱を防ぎます
• Temporal／サーバーレスとのシームレスな統合：短時間だけ稼働するサーバーインスタンスで問題なく動作します

使用パターン

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

単一バンドルモードを使用する場合

✅ 次の場合に使用してください：

• 各アクティビティが新しいサーバーを起動する Temporal ワークフローで実行する場合
• 短時間だけ稼働する関数を使用するサーバーレス／Lambda 環境にデプロイする場合
• リクエストごとにコンテナーを使用するアーキテクチャを採用する場合
• サーバーインスタンスが頻繁に再起動する場合

❌ 次の場合は使用しないでください：

• 複数のバンドルを同時に扱う必要がある場合
• 長時間稼働するサーバーインスタンスを実行する場合（デフォルトモードで問題ありません）
• バンドルの状態をメモリー内で維持できる場合

設定の詳細

環境変数	デフォルト	説明
MCP_SINGLE_BUNDLE_MODE	false	単一バンドルモードを有効にします
PRESERVE_BUNDLES	false	クリーンアップ後もバンドルファイルをディスク上に保持します
MCP_BUNDLE_STORAGE	temp dir	バンドルを永続的に保存するディレクトリ

注：サーバーの再起動後もバンドルを保持するには、単一バンドルモードとともに PRESERVE_BUNDLES=true を設定する必要があります。

クイックスタート

Podman を使用する

最も簡単に始めるには、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 のドキュメントを参照してください。

手動インストール

1. Python 3.13 がインストールされていることを確認します
2. UV を使用して環境を設定します（推奨）：

# 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. 認証トークンを設定します：

export SBCTL_TOKEN=your-token

4. UV を使用してサーバーを実行します：

uv run python -m troubleshoot_mcp_server

コンテナーイメージのバリエーション

このプロジェクトでは、次の2種類のコンテナーイメージを提供します。

開発用イメージ：troubleshoot-mcp-server-dev:latest

• 目的：ローカルでの開発とテスト
• ビルド方法：./scripts/build.sh（デフォルト）
• 用途：ソースからビルドする場合、またはローカルで開発する場合
• 例：

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

本番用イメージ：troubleshoot-mcp-server:latest

• 目的：公式リリースと本番環境へのデプロイ
• ビルド方法：CI/CD パイプラインで IMAGE_NAME=troubleshoot-mcp-server ./scripts/build.sh を実行
• 用途：本番環境、または公式リリースを使用する場合
• 例：

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

2 つのバリアントがある理由

-dev サフィックスを付けることで、ローカル開発用イメージと公式の本番リリースとの競合を防ぎます。これにより、次のことが可能になります。

• ローカルビルドの影響を受けずに公式コンテナーリリースを使用する
• 本番イメージを上書きせずに、ローカルで開発やテストを行う
• 開発環境と本番環境を明確に分離する

ドキュメント

包括的なドキュメントについては、以下をご覧ください。

• ユーザーガイド：インストール、設定、使用方法
• API リファレンス：詳細な API ドキュメント
• 開発者ガイド：開発者向け情報
• Podman ガイド：コンテナーのセットアップと設定
• システムアーキテクチャ：システム全体の設計
• トラブルシューティングガイド：一般的な問題の解決方法
• リリースプロセス：新しいリリースの作成方法

examples ディレクトリには、開発者向けのリファレンス設定が含まれています。これらのファイルは変更しないでください。

ツール

MCP サーバーは、AI モデル向けに以下のツールを提供します。

バンドル管理

• initialize_bundle：サポートバンドルを使用できるように初期化します

Kubectl コマンド

• kubectl：バンドルに対して kubectl コマンドを実行します

ファイル操作

• list_files：ファイルとディレクトリを一覧表示します
• read_file：ファイルの内容を読み取ります
• grep_files：ファイル内のパターンを検索します

使用例

AI モデルは、MCP プロトコルを使用してサーバーとやり取りできます。

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

プロジェクト構成

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

依存関係の管理について詳しくは、依存関係管理ガイドをご覧ください。

コードスタイル

コードのフォーマットには Ruff を使用します。

# Format code with Ruff
uv run ruff format .

# Lint code with Ruff
uv run ruff check .

テスト

# 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

要件

• Python 3.13
• kubectl コマンドラインツール
• バンドル管理用の sbctl コマンドラインツール
• 認証用トークン（SBCTL_TOKEN または REPLICATED 環境変数として設定）

すべての依存関係が Podman コンテナーに含まれているため、推奨されるデプロイ方法です。

コントリビューション

コントリビューションを歓迎します。コントリビューションの方法について詳しくは、開発者ガイドをご覧ください。

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。