mcp-croit-ceph

MCP Croit Ceph

通过 Model Context Protocol（MCP）对 Croit Ceph 集群进行 AI 驱动的管理

将 AI 助手（如 Claude）直接连接到 Croit Ceph 集群，实现智能集群管理、故障排查和监控。

这是什么？

一个 MCP 服务，可让 AI 助手访问 Croit Ceph 集群的 REST API。你可以向 AI 提问：

• “显示所有出现错误的存储池”
• “列出服务器 node-5 上的所有 OSD”
• “搜索过去一小时内的慢请求日志”
• “集群的运行状况是什么？”

然后，AI 就可以通过自然语言与你的集群交互。

主要功能

🚀 智能且高效

• 自动优化 token - 优化响应，将 AI token 成本降低 80-95%
• 字段选择 - 只请求所需数据（例如，仅请求 id + name）
• 内置筛选 - 无需多次调用 API，即可进行类似 grep 的搜索
• 智能摘要 - 为大型数据集生成智能摘要，并支持进一步查询

🔍 高级日志搜索

• 原生集成 VictoriaLogs，提供强大的日志分析能力
• 自然语言查询：“查找过去 24 小时内 OSD 故障”
• 检测模式并识别异常
• 为常见问题预置调试模板

🛡️ 可用于生产环境

• 基于角色的访问控制（ADMIN 与 VIEWER）
• 自动从集群发现 API
• 支持 Docker，并附带 OpenAPI 规范
• 全面的错误处理

快速开始

使用 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"
      ]
    }
  }
}

优化配置（推荐 - 启动时间从 5s 缩短至 2s）：

{
  "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 Token

1. 登录 Croit 集群的 Web 界面
2. 前往 Settings → API Tokens
3. 创建具有适当权限的新 token
4. 复制 token 并在配置中使用

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

功能详解

Token 优化

该服务会自动减少 AI token 消耗：

未优化	优化后	节省
100 个存储池，所有字段 → 4,000 个 token	100 个存储池，id+name → 300 个 token	92%
500 个 OSD，完整数据 → 15,000 个 token	智能摘要 → 1,000 个 token	93%

工作原理：

1. 字段选择：只请求所需字段
2. 智能摘要：为大型数据集生成摘要，并支持进一步查询
3. 缓存：重复请求使用缓存数据
4. 自动限制：合理的默认值可防止 token 数量激增

可用工具

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 Web 界面中验证令牌
• 检查令牌是否已过期
• 确保令牌具有正确的权限

连接问题：

• 确认 CROIT_HOST 正确（包含 https://）
• 检查与集群的网络连接
• 确认防火墙允许连接

未显示工具：

• 检查 Docker 日志中是否有错误
• 确认 OpenAPI 规范有效
• 尝试使用 --no-permission-check 进行测试

启用调试日志：

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

文档

• 架构 - 技术架构与设计
• 令牌优化 - 优化机制的工作原理
• Claude 集成 - 使用 Claude 的技巧

贡献

欢迎贡献！请：

1. Fork 仓库
2. 创建功能分支
3. 进行修改
4. 对 Python 文件运行 black 格式化工具
5. 提交 pull request

许可证

详情请参阅 LICENSE

支持

• 问题反馈：GitHub Issues
• Croit 支持：咨询集群相关问题
• MCP 协议：Model Context Protocol 文档

---

为 Ceph 社区倾心打造 ❤️