MCP Croit Ceph

MCP相信Ceph

通过模型上下文协议（MCP）对Croit Ceph集群进行AI驱动的管理

将您的AI助手（如Claude）直接连接到Croit Ceph集群，以进行智能集群管理、故障排除和监控。

这是什么？

一个MCP服务器，允许AI助手访问您的Croit Ceph集群的REST API。让你的AI：

• “显示所有有错误的池”
• “列出服务器node-5上的操作系统”
• “搜索过去一小时内慢速请求的日志”
• “群集运行状况如何？”

然后，AI可以通过自然语言与您的集群进行交互。

主要特点

🚀 智能高效

• 自动令牌优化 -优化响应，节省80-95%的AI代币成本
• 字段选择 -只请求您需要的数据（例如，只请求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

使用克劳德桌面

增添 ~/.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"
      ]
    }
  }
}

优化配置 （建议启动2秒，而不是5秒）：

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

看 .env.example docker使用模板。

获取API令牌

1. 登录您的Croit集群web界面
2. 首选 设置 → API令牌
3. 创建具有适当权限的新令牌
4. 复制令牌并在配置中使用它

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

详细功能

令牌优化

服务器自动减少AI代币消耗：

它是如何工作的：

1. 字段选择：仅请求必填字段
2. 智能摘要：大型数据集通过深入分析获得摘要
3. 缓存：重复请求使用缓存数据
4. 自动限制：合理的默认设置可防止代币爆炸

可用工具

人工智能可以使用这些工具：

核心工具：

• 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令牌的角色：

• 管理员：完全访问所有操作
• 观众：只读访问（无创建/删除/更新）
• 无效令牌：服务器退出时出错

仅限管理员类别： maintenance, servers, config, hooks

故障排除

令牌不起作用：

• 在Croit web界面中验证令牌
• 支票令牌尚未过期
• 确保令牌具有正确的权限

连接问题：

• 验证 CROIT_HOST 正确（包括https://）
• 检查群集的网络连接
• 验证防火墙是否允许连接

没有工具显示：

• 检查Docker日志是否有错误
• 验证OpenAPI规范是否有效
• 尝试 --no-permission-check 测试

启用调试日志记录：

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

文档

• 建筑 -技术架构和设计
• 令牌优化 -优化是如何工作的
• 克劳德集成 -与Claude一起使用的提示

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 跑 black Python文件的格式化程序
5. 提交拉取请求

许可证

看 许可证 详见

支持

• 问题:
• 相信支持针对特定集群的问题
• MCP协议: 模型上下文协议文档

______________________________________________________________________

由以下材料制成❤️ 为了Ceph社区