Ceph MCP 服务器

这是一个模型上下文协议（MCP）服务器，它使AI助手能够通过自然语言与Ceph存储集群进行交互。该服务器在AI工具和您的Ceph基础设施之间提供了一个桥梁，使得存储管理更加便捷和直观。

🚀 特性

• 健康监控：获取全面的集群健康状态和诊断信息
• 主机管理：监控和管理集群主机及其服务
• 详细分析：访问详细的健康检查以进行故障排除
• 安全通信：通过认证访问Ceph Manager API
• 结构化响应：生成易于AI理解的输出格式，以便清晰沟通
• 异步架构：非阻塞操作以提高性能

📋 先决条件

• Python 3.11或更高版本
• UV包管理器
• 可访问具有启用Manager API的Ceph集群
• 具有适当权限的有效Ceph凭据

🛠️ 安装

1. 克隆并设置项目：

# 创建项目目录
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

2. 设置环境：

# 复制示例环境文件
cp .env.example .env

# 使用nano编辑.env文件，填写您的Ceph集群详情
nano .env

3. 配置您的Ceph连接：

# .env文件内容
CEPH_MANAGER_URL=https://192.16.0.31:8443
CEPH_USERNAME=admin
CEPH_PASSWORD=your_ceph_password
CEPH_SSL_VERIFY=false  # 生产环境中使用正确的证书时设置为true

🏃‍♂️ 快速开始

1. 启动MCP服务器：

uv run python -m ceph_mcp.server

2. 测试连接： 服务器将记录其启动情况及任何连接问题。查看指示成功连接到您的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	日志级别（DEBUG, INFO, WARNING, ERROR）	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 助手: "我的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 Manager是否正在运行且可访问
   • 验证配置中的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 存储 - 分布式存储系统
• 模型上下文协议 - 使AI集成的协议
• Anthropic - 开发MCP和Claude

📞 支持

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