mcp-croit-ceph

MCP Croit Ceph

Model Context Protocol（MCP）を介した、Croit Ceph クラスターの AI による管理

AI アシスタント（Claude など）を Croit Ceph クラスターに直接接続して、インテリジェントなクラスター管理、トラブルシューティング、監視を行えます。

これは何ですか？

AI アシスタントが Croit Ceph クラスターの REST API にアクセスできるようにする MCP サーバーです。AI に次のように尋ねられます。

• 「エラーのあるプールをすべて表示して」
• 「サーバー node-5 上の OSD を一覧表示して」
• 「過去 1 時間の遅延リクエストについてログを検索して」
• 「クラスターのヘルスステータスは？」

AI は自然言語を通じて、クラスターを操作できます。

主な機能

🚀 スマートで効率的

• トークンの自動最適化 - AI のトークンコストを 80～95% 削減できるよう、応答を最適化します
• フィールド選択 - 必要なデータのみをリクエストできます（例：id + name のみ）
• フィルタリング機能を標準搭載 - 複数回の API 呼び出しを行わずに grep のような検索ができます
• インテリジェントな要約 - 大規模なデータセットをスマートに要約し、詳細を掘り下げられます

🔍 高度なログ検索

• 強力なログ分析を可能にする、VictoriaLogs とのネイティブ統合
• 自然言語でのクエリ：「過去 24 時間の OSD 障害を検索して」
• パターン検出と異常の特定
• よくある問題に対応した、事前構築済みのデバッグテンプレート

🛡️ 本番環境対応

• ロールベースのアクセス制御（ADMIN と VIEWER）
• クラスターからの API 自動検出
• OpenAPI 仕様書を同梱した Docker サポート
• 包括的なエラー処理

クイックスタート

Docker を使用する場合（推奨）

docker run --rm -i \
  -e CROIT_HOST="https://your-cluster.com" \
  -e CROIT_API_TOKEN="your-api-token" \
  croit/mcp-croit-ceph:latest

Claude Desktop を使用する場合

~/.config/claude/claude_desktop_config.json に追加します。

基本構成（起動時に OpenAPI 仕様書を取得します）：

{
  "mcpServers": {
    "croit-ceph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CROIT_HOST=http://your-cluster.croit.io:8080",
        "-e", "CROIT_API_TOKEN=your-api-token-here",
        "croit/mcp-croit-ceph:latest"
      ]
    }
  }
}

最適化された構成（推奨 — 起動時間を 5 秒から 2 秒に短縮します）：

{
  "mcpServers": {
    "croit-ceph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/absolute/path/to/openapi.json:/config/openapi.json:ro",
        "-e", "CROIT_HOST=http://your-cluster.croit.io:8080",
        "-e", "CROIT_API_TOKEN=your-api-token-here",
        "-e", "OPENAPI_FILE=/config/openapi.json",
        "croit/mcp-croit-ceph:latest"
      ]
    }
  }
}

デバッグログを有効にする場合：

{
  "mcpServers": {
    "croit-ceph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CROIT_HOST=http://your-cluster.croit.io:8080",
        "-e", "CROIT_API_TOKEN=your-api-token-here",
        "-e", "LOG_LEVEL=DEBUG",
        "croit/mcp-croit-ceph:latest"
      ]
    }
  }
}

注： ボリュームマウントには絶対パスが必要です（~/ は使用できません）。OpenAPI 仕様書をダウンロードするには：

curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://your-cluster.croit.io:8080/api/swagger.json > openapi.json

構成を変更した後、Claude Desktop を再起動してください。

構成

必須の環境変数

CROIT_HOST="https://your-cluster.com"      # Your Croit cluster URL
CROIT_API_TOKEN="your-api-token"           # API token from Croit

任意の環境変数

# Use local OpenAPI spec for faster startup (2s vs 5s)
OPENAPI_FILE="/config/openapi.json"

# Use bundled spec (no external fetch, for offline/dev)
USE_INCLUDED_API_SPEC="true"

# Logging verbosity: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL="INFO"

# Pass additional CLI arguments
MCP_ARGS="--no-permission-check --max-category-tools 5"

Docker の使用テンプレートについては、.env.example を参照してください。

API トークンの取得

1. Croit クラスターの Web インターフェースにログインします
2. Settings → API Tokens に移動します
3. 適切な権限を持つ新しいトークンを作成します
4. トークンをコピーして構成で使用します

AI との会話例

クラスターのヘルス状態を確認する：

You: "What's the current cluster status?"
AI: Calls list_endpoints → Finds status endpoint → Returns health summary

問題を見つける：

You: "Show me all pools with errors"
AI: Calls /pools with fields=["id","name","status"] and filter for errors
    Returns only the 3 pools with issues (instead of all 100 pools)

問題をデバッグする：

You: "Search logs for OSD failures in the last hour"
AI: Uses croit_log_search with smart query parsing
    Returns summary + drill-down capability for details

容量を計画する：

You: "Which pools are over 80% full?"
AI: Gets pools → Filters by usage → Returns list with recommendations

機能の詳細

トークンの最適化

サーバーは AI のトークン消費量を自動的に削減します。

最適化なし	最適化あり	削減率
100 個のプール、すべてのフィールド → 4,000 トークン	100 個のプール、id+name → 300 トークン	92%
500 個の OSD、すべてのデータ → 15,000 トークン	スマートな要約 → 1,000 トークン	93%

仕組み：

1. フィールド選択：必要なフィールドのみをリクエストします
2. スマートな要約：大規模なデータセットを要約し、詳細を掘り下げられるようにします
3. キャッシュ：繰り返しのリクエストではキャッシュ済みデータを使用します
4. 自動制限：妥当なデフォルト値により、トークンの急増を防ぎます

利用可能なツール

AI は次のツールを利用できます。

コアツール：

• list_endpoints - 利用可能な API エンドポイントを検出します
• call_endpoint - 最適化を適用して API を呼び出します
• search_last_result - 大きな応答の詳細を掘り下げます

カテゴリ別ツール（自動生成）：

• manage_services - Ceph サービス
• manage_pools - ストレージプール
• manage_servers - クラスターサーバー
• manage_s3 - S3 バケット
• その他...

ログ検索：

• croit_log_search - 高度なログ分析
• croit_log_check - ログ条件のクイックチェック

高度な使い方

ローカル開発

# Clone repository
git clone https://github.com/croit/mcp-croit-ceph.git
cd mcp-croit-ceph

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run directly
export CROIT_HOST="https://your-cluster.com"
export CROIT_API_TOKEN="your-token"
python mcp-croit-ceph.py

ローカルの OpenAPI 仕様書を使用する

起動を高速化する場合や、オフラインで開発する場合：

# Download spec from your cluster
curl -H "Authorization: Bearer $CROIT_API_TOKEN" \
     https://your-cluster/api/swagger.json > openapi.json

# Use local spec
python mcp-croit-ceph.py --openapi-file openapi.json

コマンドラインオプション

python mcp-croit-ceph.py \
  --openapi-file openapi.json \      # Use local OpenAPI spec
  --no-permission-check \            # Skip role check (faster)
  --max-category-tools 5             # Limit category tools

権限とセキュリティ

サーバーは API トークンのロールに従います。

• ADMIN：すべての操作へのフルアクセス
• VIEWER：読み取り専用アクセス（作成／削除／更新は不可）
• 無効なトークン：サーバーはエラーで終了します

管理者専用のカテゴリ：maintenance、servers、config、hooks

トラブルシューティング

トークンが機能しない場合：

• Croit のウェブインターフェースでトークンを確認します
• トークンの有効期限が切れていないことを確認します
• トークンに適切な権限があることを確認します

接続に関する問題：

• CROIT_HOST が正しいことを確認します（https:// を含めます）
• クラスターへのネットワーク接続を確認します
• ファイアウォールで接続が許可されていることを確認します

ツールが表示されない場合：

• Docker のログでエラーを確認します
• OpenAPI 仕様が有効であることを確認します
• --no-permission-check を試してテストします

デバッグログを有効にする：

export LOG_LEVEL=DEBUG
python mcp-croit-ceph.py

ドキュメント

• アーキテクチャ - 技術アーキテクチャと設計
• トークンの最適化 - 最適化の仕組み
• Claude との連携 - Claude で使用するためのヒント

コントリビューション

コントリビューションを歓迎します。以下の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. Python ファイルに black フォーマッターを実行します
5. プルリクエストを送信します

ライセンス

詳細は LICENSE を参照してください。

サポート

• 問題：GitHub の問題
• Croit サポート：クラスター固有の質問はこちら
• MCP プロトコル：Model Context Protocol のドキュメント

---

Ceph コミュニティのために ❤️ を込めて作成