Ceph MCP Server

🚀 Ceph MCP Server

Model Context Protocol (MCP)サーバーです。このサーバーを通じて、AIアシスタントが自然言語でCephストレージクラスタと対話できるようになります。AIツールとCephインフラストラクチャの橋渡しを行い、ストレージ管理をよりアクセスしやすく、直感的なものにします。

🚀 クイックスタート

サーバーの起動

uv run python -m ceph_mcp.server

接続のテスト

サーバーは起動時にログを出力し、接続に関する問題があればそれを表示します。Cephクラスタへの接続が成功したことを示すメッセージを探してください。

✨ 主な機能

• クラスタの健全性監視：包括的なクラスタの健全性ステータスと診断情報を取得します。
• ホスト管理：クラスタのホストとそのサービスを監視および管理します。
• 詳細分析：トラブルシューティングのための詳細な健全性チェックにアクセスします。
• 安全な通信：CephマネージャAPIへの認証付きアクセスを提供します。
• 構造化されたレスポンス：明確な通信のために、AIに適した出力形式を提供します。
• 非同期アーキテクチャ：パフォーマンス向上のための非ブロッキング操作をサポートします。

📦 インストール

前提条件

• Python 3.11以上
• UVパッケージマネージャ
• Manager APIが有効になっているCephクラスタへのアクセス
• 適切な権限を持つ有効なCeph資格情報

インストール手順

1. プロジェクトのクローンとセットアップ

# プロジェクトディレクトリの作成
mkdir ceph-mcp-server
cd ceph-mcp-server

# UVプロジェクトの初期化
uv init --python 3.11

# 依存関係の追加
uv add mcp httpx pydantic python-dotenv structlog asyncio-mqtt
uv add --dev pytest pytest-asyncio black isort mypy ruff

2. 環境のセットアップ

# 環境ファイルのコピー
cp .env.example .env

# .envファイルの編集
nano .env

3. Ceph接続の設定

# .envファイルの内容
CEPH_MANAGER_URL=https://192.16.0.31:8443
CEPH_USERNAME=admin
CEPH_PASSWORD=your_ceph_password
CEPH_SSL_VERIFY=false  # 本番環境では適切な証明書を使用してtrueに設定

💻 使用例

基本的な使用法

uv run python -m ceph_mcp.server

高度な使用法

# デバッグログを有効にする
LOG_LEVEL=DEBUG uv run python -m ceph_mcp.server

📚 ドキュメント

環境変数

セキュリティに関する考慮事項

• 本番環境での使用：本番環境では常にSSL検証 (CEPH_SSL_VERIFY=true) を有効にしてください。
• 資格情報：資格情報を安全に保管し、バージョン管理システムにコミットしないでください。
• ネットワークアクセス：MCPサーバーがCephマネージャAPIエンドポイントに到達できることを確認してください。
• 権限：最小限の必要な権限を持つ専用のCephユーザーを使用してください。

利用可能なツール

MCPサーバーは、AIアシスタント用の4つの主要なツールを提供します。

1. get_cluster_health

包括的なクラスタの健全性ステータス（全体的な健全性、警告、統計情報など）を取得します。

使用例

• "私のCephクラスタはどのような状態ですか？"
• "私が知っておくべきストレージの問題はありますか？"
• "私のクラスタの現在のステータスは何ですか？"

2. get_host_status

クラスタ内のすべてのホストに関する情報（オンライン/オフラインステータス、サービスの配布など）を取得します。

使用例

• "私のクラスタでオンラインのホストはどれですか？"
• "各ホストで実行されているサービスは何ですか？"
• "何かの問題があるホストはありますか？"

3. get_health_details

特定の問題をトラブルシューティングするための詳細な健全性チェック情報を取得します。

使用例

• "私のクラスタにはどのような特定の警告がありますか？"
• "クラスタのエラーに関する詳細情報を教えてください"
• "このストレージの問題をトラブルシューティングしてください"

4. get_host_details

特定のホストに関する包括的な情報を取得します。

パラメータ

• hostname: 調査するホストの名前

使用例

• "ホストceph - node - 01について教えてください"
• "この特定のホストで実行されているサービスは何ですか？"
• "このホストの詳細な仕様を取得してください"

対話例

健全性チェック

AIアシスタント: "私のCephクラスタはどのような状態ですか？"

レスポンス: ✅ クラスタは健全です。すべての3つのホストがオンラインです。OSD: 12/12 アップ。
🟢 全体的なステータス: HEALTH_OK
🖥️  ホスト: 3/3 オンライン
💾 OSD: 12/12 アップ

トラブルシューティング

AIアシスタント: "私のクラスタにはどのような警告がありますか？"

レスポンス: 🟡 クラスタには注意が必要な2つの警告があります。
🟡 注意が必要な警告:
   - OSD_NEARFULL: 1つのOSDがフルに近づいています
   - POOL_BACKFILLFULL: 1つのプールがバックフィルでフルになっています

開発

テストの実行

# すべてのテストを実行
uv run pytest

# カバレッジ付きで実行
uv run pytest --cov=ceph_mcp

# 特定のテストタイプを実行
uv run pytest -m "not integration"  # 統合テストをスキップ

コード品質

# コードのフォーマット
uv run black src/ tests/
uv run isort src/ tests/

# コードのリント
uv run ruff check src/ tests/
uv run mypy src/

# すべてのチェック
uv run ruff check src/ tests/ && uv run mypy src/ && uv run pytest

プロジェクト構造

ceph-mcp-server/
├── src/ceph_mcp/
│   ├── __init__.py          # パッケージの初期化
│   ├── server.py            # メインのMCPサーバー
│   ├── api/
│   │   └── ceph_client.py   # Ceph APIクライアント
│   ├── config/
│   │   └── settings.py      # 設定管理
│   ├── handlers/
│   │   └── health_handlers.py # リクエストハンドラー
│   ├── models/
│   │   └── ceph_models.py   # データモデル
│   └── utils/               # ユーティリティ関数
├── tests/                   # テストスイート
├── .env.example            # 環境テンプレート
├── pyproject.toml          # プロジェクト設定
└── README.md              # このファイル

トラブルシューティング

一般的な問題

1. 接続拒否
   • Cephマネージャが実行中でアクセス可能か確認してください。
   • 設定内のURLとポートを確認してください。
   • MCPサーバーとCephクラスタ間のネットワーク接続を確認してください。
2. 認証失敗
   • ユーザー名とパスワードが正しいことを確認してください。
   • ユーザーが適切な権限を持っていることを確認してください。
   • Cephユーザーアカウントがアクティブであることを確認してください。
3. SSL証明書エラー
   • 開発環境では、CEPH_SSL_VERIFY=falseに設定してください。
   • 本番環境では、適切なSSL証明書を使用するか、CEPH_CERT_PATHを指定してください。
4. 権限拒否
   • Cephユーザーが健全性とホスト情報の読み取り権限を持っていることを確認してください。
   • Cephユーザーの機能をチェックします: ceph auth get client.your - username

デバッグ

詳細な情報を取得するには、デバッグログを有効にします。

LOG_LEVEL=DEBUG uv run python -m ceph_mcp.server

コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します: git checkout -b feature - name
3. 変更を加え、テストを追加します。
4. テストスイートを実行します: uv run pytest
5. コードをフォーマットします: uv run black src/ tests/
6. プルリクエストを送信します。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

🙏 謝辞

• Ceph Storage - 分散ストレージシステム
• Model Context Protocol - AI統合を可能にするプロトコル
• Anthropic - MCPとClaudeの開発

📞 サポート

• バグ報告や機能リクエストについては、イシューを作成してください。
• 新しいイシューを作成する前に、既存のイシューを確認してください。
• イシューを報告する際には、環境に関する詳細情報を提供してください。