Ceph MCP服务器
一种模型上下文协议（MCP）服务器，使AI助手能够通过自然语言与Ceph存储集群进行交互。该服务器在AI工具和Ceph基础设施之间架起了一座桥梁，使存储管理更易于访问和直观。
🚀 特性
- 健康监测：获取全面的群集运行状况和诊断
- 主机管理：监视和管理群集主机及其服务
- 详细分析：访问详细的健康检查以进行故障排除
- 安全通信：通过身份验证访问Ceph Manager API
- 结构化响应：AI友好的输出格式，便于清晰沟通
- 异步架构：无阻塞操作，性能更佳
📋 先决条件
- Python 3.11或更高版本
- UV包管理器
- 访问启用了管理器API的Ceph集群
- 具有适当权限的有效Ceph凭据
🛠️ 安装
- 克隆并设置项目：
# Create the project directory
mkdir ceph-mcp-server
cd ceph-mcp-server
# Initialize UV project
uv init --python 3.11
# Add dependencies
uv add mcp httpx pydantic python-dotenv structlog asyncio-mqtt
uv add --dev pytest pytest-asyncio black isort mypy ruff- 设置您的环境：
# Copy the example environment file
cp .env.example .env
# Edit .env with your Ceph cluster details
nano .env- 配置您的Ceph连接：
# .env file contents
CEPH_MANAGER_URL=https://192.16.0.31:8443
CEPH_USERNAME=admin
CEPH_PASSWORD=your_ceph_password
CEPH_SSL_VERIFY=false # Set to true in production with proper certificates🏃♂️ 快速开始
- 启动MCP服务器：
uv run python -m ceph_mcp.server- 测试连接：
服务器将记录其启动和任何连接问题。查找指示成功连接到Ceph集群的消息。
🔧 配置
环境变量
| 变量 | 描述 | 默认值 | 必填 |
|---|---|---|---|
CEPH_MANAGER_URL | Ceph Manager 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 | 日志记录级别（调试、信息、警告、错误） | INFO | 没有 |
MAX_REQUESTS_PER_MINUTE | API请求的速率限制 | 60 | 没有 |
安全考虑
- 生产使用：始终启用SSL验证(
CEPH_SSL_VERIFY=true)生产中 - 凭证：安全地存储凭据，永远不要将其提交给版本控制
- 网络接入：确保MCP服务器能够到达Ceph Manager 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 Assistant: "How is my Ceph cluster doing?"
Response: ✅ Cluster is healthy. All 3 hosts are online. OSDs: 12/12 up.
🟢 Overall Status: HEALTH_OK
🖥️ Hosts: 3/3 online
💾 OSDs: 12/12 up故障排除
AI Assistant: "What warnings does my cluster have?"
Response: 🟡 Cluster has 2 warning(s) requiring attention.
🟡 Warnings requiring attention:
- OSD_NEARFULL: 1 osd(s) are getting full
- POOL_BACKFILLFULL: 1 pool(s) are backfill full🧪 发展
运行测试
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=ceph_mcp
# Run specific test types
uv run pytest -m "not integration" # Skip integration tests代码质量
# Format code
uv run black src/ tests/
uv run isort src/ tests/
# Lint code
uv run ruff check src/ tests/
uv run mypy src/
# All checks
uv run ruff check src/ tests/ && uv run mypy src/ && uv run pytest项目结构
ceph-mcp-server/
├── src/ceph_mcp/
│ ├── __init__.py # Package initialization
│ ├── server.py # Main MCP server
│ ├── api/
│ │ └── ceph_client.py # Ceph API client
│ ├── config/
│ │ └── settings.py # Configuration management
│ ├── handlers/
│ │ └── health_handlers.py # Request handlers
│ ├── models/
│ │ └── ceph_models.py # Data models
│ └── utils/ # Utility functions
├── tests/ # Test suite
├── .env.example # Environment template
├── pyproject.toml # Project configuration
└── README.md # This file🐛 故障排除
常见问题
- 连接被拒绝
- 检查Ceph管理器是否正在运行且可访问 - 验证配置中的URL和端口 - 确保MCP服务器和Ceph集群之间的网络连接
- 认证失败
- 验证用户名和密码是否正确 - 检查用户是否具有适当的权限 - 确保Ceph用户帐户处于活动状态
- SSL证书错误
- 开发：Set 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许可证获得许可-有关详细信息，请参阅许可证文件。
🙏 致谢
📞 支持
- 为错误报告或功能请求创建问题
- 在创建新问题之前检查现有问题
- 在报告问题时提供有关您的环境的详细信息
