Scan to join WeChat grouparticle
README
🚀 Ceph MCP Server
Ceph MCP Server是一个模型上下文协议（MCP）服务器，它使AI助手能够通过自然语言与Ceph存储集群进行交互。该服务器在AI工具和Ceph基础设施之间架起了一座桥梁，让存储管理变得更加便捷和直观。
🚀 快速开始
启动MCP服务器
uv run python -m ceph_mcp.server
测试连接
服务器会记录其启动情况和任何连接问题。请留意指示已成功连接到Ceph集群的消息。
✨ 主要特性
- 健康监控：获取全面的集群健康状态和诊断信息
- 主机管理：监控和管理集群主机及其服务
- 详细分析：访问详细的健康检查信息，以进行故障排除
- 安全通信：通过身份验证访问Ceph管理器API
- 结构化响应：输出格式对AI友好，便于清晰通信
- 异步架构：非阻塞操作，以实现更好的性能
📦 安装指南
克隆并设置项目
# 创建项目目录
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
设置环境
# 复制示例环境文件
cp .env.example .env
# 使用Ceph集群详细信息编辑.env文件
nano .env
配置Ceph连接
# .env文件内容
CEPH_MANAGER_URL=https://192.16.0.31:8443
CEPH_USERNAME=admin
CEPH_PASSWORD=your_ceph_password
CEPH_SSL_VERIFY=false # 在生产环境中使用适当的证书时设置为true
🔧 技术细节
环境变量
| 属性 | 详情 |
|------|------|
| CEPH_MANAGER_URL | Ceph管理器API端点，默认值为https://192.16.0.31:8443，必需 |
| CEPH_USERNAME | 用于API访问的Ceph用户名，默认值为admin，必需 |
| CEPH_PASSWORD | 用于身份验证的Ceph密码，必需 |
| CEPH_SSL_VERIFY | 启用SSL证书验证，默认值为true，非必需 |
| CEPH_CERT_PATH | 自定义SSL证书的路径，非必需 |
| LOG_LEVEL | 日志记录级别（DEBUG、INFO、WARNING、ERROR），默认值为INFO，非必需 |
| MAX_REQUESTS_PER_MINUTE | API请求的速率限制，默认值为60，非必需 |
安全注意事项
- 生产环境使用：在生产环境中始终启用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个存储池回填已满
🧪 开发
运行测试
# 运行所有测试
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 # 本文件
🐛 故障排除
常见问题
-
连接被拒绝
- 检查Ceph管理器是否正在运行且可访问
- 验证配置中的URL和端口
- 确保MCP服务器和Ceph集群之间的网络连接正常
-
身份验证失败
- 验证用户名和密码是否正确
- 检查用户是否具有适当的权限
- 确保Ceph用户账户处于活动状态
-
SSL证书错误
- 开发环境：将
CEPH_SSL_VERIFY设置为false - 生产环境：使用适当的SSL证书或指定
CEPH_CERT_PATH
- 开发环境：将
-
权限被拒绝
- 确保Ceph用户对健康和主机信息具有读取权限
- 检查Ceph用户权限：
ceph auth get client.your-username
调试
启用调试日志记录以获取更详细的信息：
LOG_LEVEL=DEBUG uv run python -m ceph_mcp.server
🤝 贡献代码
- 分叉仓库
- 创建功能分支：
git checkout -b feature-name - 进行更改并添加测试
- 运行测试套件：
uv run pytest - 格式化代码：
uv run black src/ tests/ - 提交拉取请求
📄 许可证
本项目采用MIT许可证 - 有关详细信息，请参阅LICENSE文件。
🙏 致谢
- Ceph Storage - 分布式存储系统
- Model Context Protocol - 支持AI集成的协议
- Anthropic - 开发MCP和Claude的公司
📞 支持
- 若要报告错误或请求功能，请创建一个问题
- 在创建新问题之前，请检查现有问题
- 报告问题时，请提供有关您的环境的详细信息