Ceph MCP Server

🚀 Ceph MCP Server

Ceph MCP Server 是一個模型上下文協議（MCP）服務器，它使 AI 助手能夠通過自然語言與 Ceph 存儲集群進行交互。該服務器在 AI 工具和你的 Ceph 基礎設施之間架起了一座橋樑，讓存儲管理變得更加便捷和直觀。

🚀 快速開始

啟動 MCP 服務器

uv run python -m ceph_mcp.server

測試連接

服務器將記錄其啟動情況和任何連接問題。查找表明已成功連接到 Ceph 集群的消息。

✨ 主要特性

• 健康監測：獲取全面的集群健康狀態和診斷信息
• 主機管理：監控和管理集群主機及其服務
• 詳細分析：訪問詳細的健康檢查以進行故障排除
• 安全通信：對 Ceph 管理器 API 進行身份驗證訪問
• 結構化響應：採用對 AI 友好的輸出格式，實現清晰的通信
• 異步架構：非阻塞操作，以獲得更好的性能

📦 安裝指南

前置條件

• Python 3.11 或更高版本
• UV 包管理器
• 能夠訪問啟用了管理器 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

# 使用 Ceph 集群詳細信息編輯 .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

📚 詳細文檔

環境變量

安全注意事項

• 生產環境使用：在生產環境中始終啟用 SSL 驗證（CEPH_SSL_VERIFY=true）
• 憑證：安全存儲憑證，切勿將其提交到版本控制系統
• 網絡訪問：確保 MCP 服務器能夠訪問你的 Ceph 管理器 API 端點
• 權限：使用具有最低所需權限的專用 Ceph 用戶

可用工具

MCP 服務器為 AI 助手提供了四個主要工具：

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 個存儲池回填已滿

💻 使用示例

基礎用法

# 啟動 MCP 服務器
uv run python -m ceph_mcp.server

高級用法

# 運行所有測試
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

📞 支持

• 若要報告錯誤或請求功能，請創建一個 issue
• 在創建新 issue 之前，請檢查現有 issue
• 報告問題時，請提供有關你環境的詳細信息