Ceph MCP Server

🚀 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

🔧 技术细节

环境变量

安全注意事项

• 生产环境使用：在生产环境中始终启用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              # 本文件

🐛 故障排除

常见问题

1. 连接被拒绝

   • 检查Ceph管理器是否正在运行且可访问
   • 验证配置中的URL和端口
   • 确保MCP服务器和Ceph集群之间的网络连接正常

2. 身份验证失败

   • 验证用户名和密码是否正确
   • 检查用户是否具有适当的权限
   • 确保Ceph用户账户处于活动状态

3. SSL证书错误

   • 开发环境：将CEPH_SSL_VERIFY设置为false
   • 生产环境：使用适当的SSL证书或指定CEPH_CERT_PATH

4. 权限被拒绝

   • 确保Ceph用户对健康和主机信息具有读取权限
   • 检查Ceph用户权限：ceph auth get client.your-username

调试

启用调试日志记录以获取更详细的信息：

LOG_LEVEL=DEBUG uv run python -m ceph_mcp.server

🤝 贡献代码

1. 分叉仓库
2. 创建功能分支：git checkout -b feature-name
3. 进行更改并添加测试
4. 运行测试套件：uv run pytest
5. 格式化代码：uv run black src/ tests/
6. 提交拉取请求

📄 许可证

本项目采用MIT许可证 - 有关详细信息，请参阅LICENSE文件。

🙏 致谢

• Ceph Storage - 分布式存储系统
• Model Context Protocol - 支持AI集成的协议
• Anthropic - 开发MCP和Claude的公司

📞 支持

• 若要报告错误或请求功能，请创建一个问题
• 在创建新问题之前，请检查现有问题
• 报告问题时，请提供有关您的环境的详细信息