MCP Croit Ceph

🚀 MCP Croit Ceph

MCP（Model Context Protocol）サーバーで、REST APIを通じてCroit Cephクラスターと相互作用できます。

🚀 クイックスタート

このMCPサーバーは、Croit Cephクラスターとの相互作用を容易にします。以下のセクションでは、インストール、設定、使用方法などの詳細を説明します。

✨ 主な機能

自動トークン最適化

MCPサーバーは、応答を自動的に最適化してトークン消費を削減します。

• 自動制限：リスト操作にデフォルトの制限（10 - 100項目）を追加します。
• スマート切り捨て：大きな応答は自動的にメタデータとともに切り捨てられます。
• 最適化ヒント：ツールの説明にはトークン節約のヒントが含まれています。
• 応答メタデータ：切り捨てられた応答には、より多くのデータを取得する方法に関する情報が含まれています。

例：500個のサービス（50,000トークン）の代わりに、25個のサービス + メタデータ（2,500トークン）が得られます。

組み込みフィルタリング（grepのような検索）

複数の呼び出しを行わずに、API応答をローカルでフィルタリングできます。

• フィールドフィルタリング：_filter_status='error' - 完全一致
• 正規表現パターン：_filter_name='~ceph.*' - パターン一致
• 数値比較：_filter_size='>1000' - より大きい
• テキスト検索：_filter__text='timeout' - すべてのテキストフィールドを検索
• フィールドの存在：_filter__has='error_message' - フィールドが存在する
• 複数の値：_filter_status=['error','warning'] - OR論理

例：1回の呼び出しで500個のサービスからエラーを見つける：

_filter_status='error' → 5つのエラーサービスのみを返す（99％のトークン節約）

ハイブリッドモード（デフォルト） - ツール数を97％削減！

新しいハイブリッドモードでは、ツール数を580個の個別エンドポイントツールからわずか13個のツールに削減します。

• 3つの基本ツール：完全なAPIアクセス用
• 10個のカテゴリツール：一般的な操作（サービス、メンテナンス、S3、プールなど）用

この大幅な削減により、以下が改善されます。

• LLMのパフォーマンスと応答時間
• ツールの発見性と使いやすさ
• メモリ効率
• 起動時間

ツール生成モード

1. hybrid（デフォルト）：基本ツールとカテゴリツールを組み合わせて最適なバランスを実現します。
2. base_only：完全なAPIアクセス用の3つの基本ツールのみ。
3. categories_only：簡素化された操作のためのカテゴリツールのみ。
4. endpoints_as_tools：レガシーモードで、580個の個別ツール（APIエンドポイントごとに1つ）を作成します。

動的機能

• 自動API検出：CroitクラスターからOpenAPI仕様を取得します。
• 権限ベースのフィルタリング：APIトークンのロールに基づいてツールをフィルタリングします（ADMIN vs VIEWER）。
• 完全なx-llm-hintsサポート：575以上のエンドポイントにAI最適化ヒントが含まれています。
• ローカルOpenAPIサポート：テスト/開発用にローカルのOpenAPI仕様ファイルを使用できます。
• スキーマ解決：$ref参照を自動的に処理します。

高度なx-llm-hints統合

MCPサーバーは、Croitのx-llm-hintsをツールの説明に完全に統合して、最適なLLMガイダンスを提供します。

x-llm-hintsが提供するもの

• 目的：各エンドポイントの機能を明確に説明します。
• 使用例：一般的な使用ケースとワークフローガイダンス。
• 失敗モード：予想されるエラーとその対処方法。
• レート制限：APIの制限情報を提供して効率的な使用を促します。
• リトライ戦略：一時的な失敗の対処方法。
• ポーリング間隔：リアルタイムデータの推奨更新間隔。
• キャッシュヒント：応答のキャッシュ戦略。
• 関連エンドポイント：複雑なワークフローのための相互参照。

統合されたヒントの例

manage_clusterツール:
目的: 選択したMONディスクとIPアドレスを使用して、新しいCephクラスターをブートストラップします。

一般的な使用方法:
• GET /cluster/create/monsから候補を取得した直後に呼び出します。
• /tasks/{id}を介して返されたManagedTaskを監視し、ブートストラップが完了するまで待ちます。

失敗モード:
• 400: GET /cluster/create/monsを介してディスク/サーバーの適格性を検証します。
• 409: 同時にブートストラップが進行中の場合は、既存のタスクが完了するのを待ちます。

レート制限: 60/300s, 30/300s
リトライ戦略: manual_retry, exponential_backoff

LLMにとってのメリット

• コンテキスト認識操作：LLMが各ツールの使用時期と方法を理解します。
• エラー処理：APIエラーの対処に関する積極的なガイダンス。
• パフォーマンス最適化：組み込みのレート制限とキャッシュ認識。
• ワークフローインテリジェンス：多段階操作の理解。

📦 インストール

⚠️ 重要提示

このプロジェクトは、システム管理のPython環境のため、仮想環境が必要です。

# リポジトリをクローンする
git clone https://github.com/croit/mcp-croit-ceph.git
cd mcp-croit-ceph

# 仮想環境を作成してアクティブ化する（必須）
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# または: venv\Scripts\activate  # Windows

# 仮想環境に依存関係をインストールする
pip install -r requirements.txt

💡 使用建议

Pythonコマンドやテストを実行する前に、常に仮想環境をアクティブ化してください（source venv/bin/activate）。

📚 ドキュメント

設定

環境変数を設定します。

export CROIT_HOST="https://your-croit-cluster.com"
export CROIT_API_TOKEN="your-api-token"

または、/config/config.jsonに設定ファイルを使用します。

{
  "host": "https://your-croit-cluster.com",
  "api_token": "your-api-token"
}

使用方法

基本的な使用法（ハイブリッドモード）

# まず仮想環境をアクティブ化する（必須）
source venv/bin/activate

# デフォルトのハイブリッドモードで権限チェックを行う
python mcp-croit-ceph.py

高度なオプション

# まず仮想環境をアクティブ化する（必須）
source venv/bin/activate

# ローカルのOpenAPI仕様ファイルを使用する
python mcp-croit-ceph.py --openapi-file openapi.json

# 権限チェックをスキップする（起動が速くなります）
python mcp-croit-ceph.py --no-permission-check

# 基本ツールのみを使用する（最小限のモード）
python mcp-croit-ceph.py --mode base_only

# カテゴリツールのみを使用する
python mcp-croit-ceph.py --mode categories_only

# すべての580個のエンドポイントツールを使用するレガシーモード（推奨しません）
python mcp-croit-ceph.py --mode endpoints_as_tools

# カテゴリツールの制限をカスタマイズする
python mcp-croit-ceph.py --max-category-tools 5

ツールモードの説明

ハイブリッドモード（推奨）

約13個のツールで最適なバランスを提供します。

基本ツール

• list_endpoints - APIエンドポイントを検索およびフィルタリングします。
• call_endpoint - 任意のエンドポイントに直接API呼び出しを行います。
• get_schema - スキーマ参照を解決します。

カテゴリツール（上位10個）

• manage_services - Cephサービスの操作
• manage_maintenance - メンテナンスタスク
• manage_s3 - S3バケット管理
• manage_pools - ストレージプールの操作
• manage_servers - サーバー管理
• など

各カテゴリツールは、list、get、create、update、deleteなどのアクションをサポートしています。

基本ツールのみのモード

完全なAPIアクセス用の3つのツールのみを使用する最小限のセットアップです。

• list_api_endpoints - 利用可能なエンドポイントを検出します。
• call_api_endpoint - API呼び出しを行います。
• get_reference_schema - スキーマを解決します。

カテゴリツールのみのモード

基本ツールを使用せず、カテゴリツールのみを使用する簡素化されたインターフェースです。

エンドポイントをツールとするモード（レガシー）

580個の個別ツール（APIエンドポイントごとに1つ）を作成します。以下の理由から推奨されません。

• パフォーマンスのオーバーヘッド
• ツールの発見が困難
• MCPクライアントの制限

権限ベースのフィルタリング

サーバーは、APIトークンのロールに基づいてツールをインテリジェントにフィルタリングします。

1. 自動ロール検出：/auth/token-infoエンドポイントを介してロールを取得します。
2. ロールベースのアクセス
   • ADMINロール：すべてのカテゴリに完全なアクセス権があります。
   • VIEWER/その他のロール：管理者専用の操作を除くすべてのカテゴリにアクセスできます。
   • 無効なトークン：サーバーはエラーで終了します（アクセス不可）。

カテゴリアクセス制御

管理者専用カテゴリ

• maintenance、servers、ipmi - システム管理
• config、hooks、change-requests - 設定変更
• config-templates - テンプレート管理

その他のすべてのカテゴリは、VIEWERロールが読み取り操作を行うためにアクセス可能です。

• cluster、status、stats - 監視
• logs、disks、services - 情報閲覧
• s3、cephfs、rbds、pools - ストレージ情報
• authentication、images、daos - 読み取り操作
• 管理者専用としてリストされていないすべてのカテゴリ

このロールベースのアプローチは高速で、ユーザーが実際に使用できるツールのみを表示することを保証します。

ローカルOpenAPI仕様の使用

オフライン開発またはテストのために、以下の手順を実行します。

# クラスターから仕様をダウンロードする
curl -H "Authorization: Bearer $CROIT_API_TOKEN" \
     https://your-cluster/api/swagger.json > openapi.json

# ローカルファイルを使用する
python mcp-croit-ceph.py --openapi-file openapi.json

MCP統合

Claude Desktopとの統合

Claude Desktopの設定に追加します。

{
  "mcpServers": {
    "croit-ceph": {
      "command": "python",
      "args": ["/path/to/mcp-croit-ceph.py"],
      "env": {
        "CROIT_HOST": "https://your-cluster",
        "CROIT_API_TOKEN": "your-token"
      }
    }
  }
}

その他のMCPクライアントとの統合

サーバーは標準のMCPプロトコルを実装しており、互換性のあるクライアントと動作します。

コマンドライン引数

Dockerの使用

Dockerでビルドして実行する

# Dockerイメージをビルドする
docker build -t mcp-croit-ceph .

# 環境変数を指定して実行する
docker run -it --rm \
  -e CROIT_HOST="https://your-cluster" \
  -e CROIT_API_TOKEN="your-token" \
  mcp-croit-ceph

# ローカルのOpenAPI仕様を使用してテストする
docker run -it --rm \
  -v $(pwd)/openapi.json:/config/openapi.json:ro \
  -e CROIT_HOST="http://dummy" \
  -e CROIT_API_TOKEN="dummy" \
  mcp-croit-ceph \
  --mode hybrid --openapi-file /config/openapi.json --no-permission-check

Docker Compose

version: '3.8'
services:
  mcp-croit-ceph:
    image: mcp-croit-ceph:latest
    environment:
      CROIT_HOST: "${CROIT_HOST}"
      CROIT_API_TOKEN: "${CROIT_API_TOKEN}"
      MCP_ARGS: "--mode hybrid"
    volumes:
      # オプション: ローカルのOpenAPI仕様を使用する
      - ./openapi.json:/config/openapi.json:ro

開発

⚠️ 重要提示

開発作業を開始する前に、常に仮想環境をアクティブ化してください。

source venv/bin/activate

テストツール数の確認

# まず仮想環境をアクティブ化する
source venv/bin/activate

# 各モードで生成されるツール数を確認する
for mode in hybrid base_only categories_only; do
  echo "$mode: $(python mcp-croit-ceph.py --mode $mode --openapi-file openapi.json --no-permission-check 2>&1 | grep -o 'Generated [0-9]* tools')"
done

デバッグロギング

# まず仮想環境をアクティブ化する
source venv/bin/activate

# デバッグロギングを有効にする
export LOG_LEVEL=DEBUG
python mcp-croit-ceph.py

ローカルOpenAPI仕様でのテスト

# まず仮想環境をアクティブ化する
source venv/bin/activate

# テストスクリプトを使用する
./test-local.sh

# または、手動で異なるモードをテストする
python mcp-croit-ceph.py --mode hybrid --openapi-file openapi.json --no-permission-check

テストの実行

# まず仮想環境をアクティブ化する
source venv/bin/activate

# タイムスタンプ修正テストを実行する
python test_timestamp_fix.py

# 他のテストを実行する（仮想環境に依存関係がインストールされていることを確認する）
python test_actual_mcp.py

📄 ライセンス

Apache 2.0

サポート

このMCPサーバーに関する問題は、このリポジトリにイシューを開いてください。Croitに関する質問は、Croitサポートに問い合わせてください。