MCP Croit Ceph

🚀 MCP Croit Ceph

MCP（模型上下文協議）服務器，用於通過Croit Ceph集群的REST API與之交互，可高效管理和操作集群。

🚀 快速開始

使用此MCP Croit Ceph服務器前，請確保你具備以下基礎條件：

1. 擁有Croit Ceph集群的訪問權限。
2. 已安裝Python 3。
3. 瞭解基本的命令行操作。

安裝步驟

# 克隆倉庫
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

配置環境

你可以通過以下兩種方式設置環境變量：

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

✨ 主要特性

自動令牌優化

MCP服務器會自動優化響應，以減少令牌消耗：

• 自動限制：為列表操作添加默認限制（10 - 100項）。
• 智能截斷：大型響應會自動截斷，並附帶元數據。
• 優化提示：工具描述中包含節省令牌的提示。
• 響應元數據：截斷的響應包含如何獲取更多數據的信息。

示例：原本需要50,000個令牌的500個服務，現在只需2,500個令牌就能獲取25個服務 + 元數據。

內置過濾（類似grep搜索）

無需多次調用，即可在本地過濾API響應：

• 字段過濾：_filter_status='error' - 精確匹配。
• 正則表達式模式：_filter_name='~ceph.*' - 模式匹配。
• 數值比較：_filter_size='>1000' - 大於比較。
• 文本搜索：_filter__text='timeout' - 搜索所有文本字段。
• 字段存在性：_filter__has='error_message' - 檢查字段是否存在。
• 多值匹配：_filter_status=['error','warning'] - 或邏輯。

示例：一次調用即可在500個服務中查找錯誤：

_filter_status='error' → 僅返回5個錯誤服務（節省99%的令牌）

混合模式（默認） - 工具數量減少97%！

新的混合模式將工具數量從580個單獨的端點工具減少到僅13個工具：

• 3個基礎工具：用於全面訪問API。
• 10個分類工具：用於常見操作（服務、維護、S3、存儲池等）。

這種顯著的減少帶來了以下提升：

• 提升LLM性能和響應時間。
• 改善工具發現和可用性。
• 提高內存效率。
• 縮短啟動時間。

工具生成模式

1. hybrid（默認）：結合基礎工具和分類工具，實現最佳平衡。
2. base_only：僅使用3個基礎工具，實現最小化配置。
3. categories_only：僅使用分類工具，提供簡化的操作界面。
4. endpoints_as_tools：傳統模式，為每個API端點創建一個工具。

動態特性

• 自動API發現：從Croit集群獲取OpenAPI規範。
• 基於權限的過濾：根據角色進行工具過濾（管理員與查看者）。
• 完全支持x-llm-hints字段：575個以上的端點帶有AI優化提示。
• 本地OpenAPI支持：可使用本地OpenAPI規範文件進行測試和開發。
• 模式解析：自動處理 $ref 引用。

高級x-llm-hints集成

MCP服務器將Croit的x-llm-hints完全集成到工具描述中，為LLM提供最佳指導：

• 用途：清晰描述每個端點的功能。
• 使用示例：提供常見用例和工作流指導。
• 失敗模式：說明預期的錯誤及處理方法。
• 速率限制：提供API限流信息，以實現高效使用。
• 重試策略：說明如何處理臨時故障。
• 輪詢間隔：推薦即時數據的刷新頻率。
• 緩存提示：提供響應緩存策略。
• 相關端點：交叉引用複雜工作流。

示例：

manage_cluster 工具：
用途：使用選定的MON磁盤和IP地址引導全新的Ceph集群。

常見用法：
• 在通過GET /cluster/create/mons獲取候選對象後立即調用。
• 通過/tasks/{id}監控返回的ManagedTask，直到引導完成。

失敗模式：
• 400：通過GET /cluster/create/mons驗證磁盤/服務器的資格。
• 409：如果正在進行併發引導，請等待現有任務完成。

速率限制：60/300s，30/300s
重試策略：手動重試，指數退避

對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)。

💻 使用示例

基礎用法（混合模式）

# 首先激活虛擬環境（必需）
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 等操作。

僅基礎工具模式

僅使用3個工具，實現最小化配置，可全面訪問API：

• list_api_endpoints - 發現可用的端點。
• call_api_endpoint - 進行API調用。
• get_reference_schema - 解析模式。

僅分類工具模式

提供簡化的界面，僅使用分類工具，不包含基礎工具。

端點即工具模式（傳統）

創建580個單獨的工具（每個API端點一個）。由於性能開銷大、工具發現困難和MCP客戶端限制，不推薦使用。

基於權限的過濾

服務器會根據API令牌的角色智能過濾工具：

1. 自動角色檢測：通過 /auth/token-info 端點獲取角色信息。
2. 基於角色的訪問：
   • 管理員角色：可以完全訪問所有類別。
   • 查看者/其他角色：可以訪問除管理員專用操作之外的所有類別。
   • 無效令牌：服務器將報錯退出（無訪問權限）。

類別訪問控制

• 管理員專用類別：
  • maintenance、servers、ipmi - 系統管理。
  • config、hooks、change-requests - 配置更改。
  • config-templates - 模板管理。
• 其他所有類別：查看者角色可以進行讀取操作：
  • 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協議，可與任何兼容的客戶端配合使用。

命令行參數

參數	描述	默認值
--mode	工具生成模式	hybrid
--openapi-file	本地OpenAPI規範文件	無（從服務器獲取）
--no-permission-check	跳過權限檢查	false（啟用檢查）
--max-category-tools	要生成的最大分類工具數量	10
--no-resolve-references	不解析規範中的 $ref	false（啟用解析）
--offer-whole-spec	在列表工具中包含完整規範	false

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支持團隊。