shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

mcp-croit-ceph

一个用于通过REST API与Croit Ceph集群交互的MCP服务器，支持自动令牌优化、内置过滤和混合模式工具管理，大幅减少工具数量并提升LLM性能。

article

README

🚀 MCP Croit Ceph

MCP（模型上下文协议）服务器，用于通过Croit Ceph集群的REST API与之交互，可高效管理和操作集群。

🚀 快速开始

使用此MCP Croit Ceph服务器前，请确保你具备以下基础条件：

  1. 拥有Croit Ceph集群的访问权限。
  2. 已安装Python 3。
  3. 了解基本的命令行操作。

安装步骤

# 克隆仓库
git clone https://github.com/croit/mcp-croit-ceph.git
cd mcp-croit-ceph

# 创建并激活虚拟环境（必需）
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或者：venv\Scripts\activate  # Windows

# 在虚拟环境中安装依赖
pip install -r requirements.txt

配置环境

你可以通过以下两种方式设置环境变量：

export CROIT_HOST="https://your-croit-cluster.com"
export CROIT_API_TOKEN="your-api-token"

或者使用配置文件 /config/config.json：

{
  "host": "https://your-croit-cluster.com",
  "api_token": "your-api-token"
}

运行示例

# 首先激活虚拟环境（必需）
source venv/bin/activate

# 默认混合模式，带有权限检查
python mcp-croit-ceph.py

✨ 主要特性

自动令牌优化

MCP服务器会自动优化响应，以减少令牌消耗：

  • 自动限制：为列表操作添加默认限制（10 - 100项）。
  • 智能截断：大型响应会自动截断，并附带元数据。
  • 优化提示：工具描述中包含节省令牌的提示。
  • 响应元数据：截断的响应包含如何获取更多数据的信息。

示例：原本需要50,000个令牌的500个服务，现在只需2,500个令牌就能获取25个服务 + 元数据。

内置过滤（类似grep搜索）

无需多次调用，即可在本地过滤API响应：

  • 字段过滤：_filter_status='error' - 精确匹配。
  • 正则表达式模式：_filter_name='~ceph.*' - 模式匹配。
  • 数值比较：_filter_size='>1000' - 大于比较。
  • 文本搜索：_filter__text='timeout' - 搜索所有文本字段。
  • 字段存在性：_filter__has='error_message' - 检查字段是否存在。
  • 多值匹配：_filter_status=['error','warning'] - 或逻辑。

示例：一次调用即可在500个服务中查找错误：

_filter_status='error' → 仅返回5个错误服务（节省99%的令牌）

混合模式（默认） - 工具数量减少97%！

新的混合模式将工具数量从580个单独的端点工具减少到仅13个工具：

  • 3个基础工具：用于全面访问API。
  • 10个分类工具：用于常见操作（服务、维护、S3、存储池等）。

这种显著的减少带来了以下提升：

  • 提升LLM性能和响应时间。
  • 改善工具发现和可用性。
  • 提高内存效率。
  • 缩短启动时间。

工具生成模式

  1. hybrid（默认）：结合基础工具和分类工具，实现最佳平衡。
  2. base_only：仅使用3个基础工具，实现最小化配置。
  3. categories_only：仅使用分类工具，提供简化的操作界面。
  4. endpoints_as_tools：传统模式，为每个API端点创建一个工具。

动态特性

  • 自动API发现：从Croit集群获取OpenAPI规范。
  • 基于权限的过滤：根据角色进行工具过滤（管理员与查看者）。
  • 完全支持x-llm-hints字段：575个以上的端点带有AI优化提示。
  • 本地OpenAPI支持：可使用本地OpenAPI规范文件进行测试和开发。
  • 模式解析：自动处理 $ref 引用。

高级x-llm-hints集成

MCP服务器将Croit的x-llm-hints完全集成到工具描述中，为LLM提供最佳指导：

  • 用途：清晰描述每个端点的功能。
  • 使用示例：提供常见用例和工作流指导。
  • 失败模式：说明预期的错误及处理方法。
  • 速率限制：提供API限流信息，以实现高效使用。
  • 重试策略：说明如何处理临时故障。
  • 轮询间隔：推荐实时数据的刷新频率。
  • 缓存提示：提供响应缓存策略。
  • 相关端点：交叉引用复杂工作流。

示例：

manage_cluster 工具：
用途：使用选定的MON磁盘和IP地址引导全新的Ceph集群。

常见用法：
• 在通过GET /cluster/create/mons获取候选对象后立即调用。
• 通过/tasks/{id}监控返回的ManagedTask，直到引导完成。

失败模式：
• 400：通过GET /cluster/create/mons验证磁盘/服务器的资格。
• 409：如果正在进行并发引导，请等待现有任务完成。

速率限制：60/300s，30/300s
重试策略：手动重试，指数退避

对LLM的好处

  • 上下文感知操作：LLM了解何时以及如何使用每个工具。
  • 错误处理：提供主动的API错误处理指导。
  • 性能优化：内置速率限制和缓存意识。
  • 工作流智能：理解多步骤操作。

📦 安装指南

⚠️ 重要提示

由于系统管理的Python环境，此项目需要使用虚拟环境。

# 克隆仓库
git clone https://github.com/croit/mcp-croit-ceph.git
cd mcp-croit-ceph

# 创建并激活虚拟环境（必需）
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或者：venv\Scripts\activate  # Windows

# 在虚拟环境中安装依赖
pip install -r requirements.txt

注意：在运行任何Python命令或测试之前，请始终激活虚拟环境 (source venv/bin/activate)。

💻 使用示例

基础用法（混合模式）

# 首先激活虚拟环境（必需）
source venv/bin/activate

# 默认混合模式，带有权限检查
python mcp-croit-ceph.py

高级用法

# 首先激活虚拟环境（必需）
source venv/bin/activate

# 使用本地OpenAPI规范文件
python mcp-croit-ceph.py --openapi-file openapi.json

# 跳过权限检查（更快启动）
python mcp-croit-ceph.py --no-permission-check

# 仅使用基础工具（最小化模式）
python mcp-croit-ceph.py --mode base_only

# 仅使用分类工具
python mcp-croit-ceph.py --mode categories_only

# 传统模式，使用所有580个端点工具（不推荐）
python mcp-croit-ceph.py --mode endpoints_as_tools

# 自定义分类工具限制
python mcp-croit-ceph.py --max-category-tools 5

📚 详细文档

工具模式说明

混合模式（推荐）

提供约13个工具，实现最佳平衡：

  • 基础工具：
    • list_endpoints - 搜索和过滤API端点。
    • call_endpoint - 直接调用任何API端点。
    • get_schema - 解析模式引用。
  • 分类工具（前10个）：
    • manage_services - Ceph服务操作。
    • manage_maintenance - 维护任务。
    • manage_s3 - S3存储桶管理。
    • manage_pools - 存储池操作。
    • manage_servers - 服务器管理。
    • 等等...

每个分类工具支持 list、get、create、update、delete 等操作。

仅基础工具模式

仅使用3个工具，实现最小化配置，可全面访问API：

  • list_api_endpoints - 发现可用的端点。
  • call_api_endpoint - 进行API调用。
  • get_reference_schema - 解析模式。

仅分类工具模式

提供简化的界面，仅使用分类工具，不包含基础工具。

端点即工具模式（传统）

创建580个单独的工具（每个API端点一个）。由于性能开销大、工具发现困难和MCP客户端限制，不推荐使用。

基于权限的过滤

服务器会根据API令牌的角色智能过滤工具：

  1. 自动角色检测：通过 /auth/token-info 端点获取角色信息。
  2. 基于角色的访问：
    • 管理员角色：可以完全访问所有类别。
    • 查看者/其他角色：可以访问除管理员专用操作之外的所有类别。
    • 无效令牌：服务器将报错退出（无访问权限）。

类别访问控制

  • 管理员专用类别：
    • maintenance、servers、ipmi - 系统管理。
    • config、hooks、change-requests - 配置更改。
    • config-templates - 模板管理。
  • 其他所有类别：查看者角色可以进行读取操作：
    • cluster、status、stats - 监控。
    • logs、disks、services - 信息查看。
    • s3、cephfs、rbds、pools - 存储信息。
    • authentication、images、daos - 读取操作。
    • 以及所有未列为管理员专用的类别。

这种基于角色的方法速度快，可确保用户只能看到他们实际可以使用的工具。

使用本地OpenAPI规范

对于离线开发或测试：

# 从集群下载规范
curl -H "Authorization: Bearer $CROIT_API_TOKEN" \
     https://your-cluster/api/swagger.json > openapi.json

# 使用本地文件
python mcp-croit-ceph.py --openapi-file openapi.json

MCP集成

与Claude Desktop集成

将以下配置添加到Claude Desktop配置文件中：

{
  "mcpServers": {
    "croit-ceph": {
      "command": "python",
      "args": ["/path/to/mcp-croit-ceph.py"],
      "env": {
        "CROIT_HOST": "https://your-cluster",
        "CROIT_API_TOKEN": "your-token"
      }
    }
  }
}

与其他MCP客户端集成

服务器实现了标准的MCP协议，可与任何兼容的客户端配合使用。

命令行参数

| 参数 | 描述 | 默认值 | |------|------|--------| | --mode | 工具生成模式 | hybrid | | --openapi-file | 本地OpenAPI规范文件 | 无（从服务器获取） | | --no-permission-check | 跳过权限检查 | false（启用检查） | | --max-category-tools | 要生成的最大分类工具数量 | 10 | | --no-resolve-references | 不解析规范中的 $ref | false（启用解析） | | --offer-whole-spec | 在列表工具中包含完整规范 | false |

Docker使用

使用Docker构建和运行

# 构建Docker镜像
docker build -t mcp-croit-ceph .

# 使用环境变量运行
docker run -it --rm \
  -e CROIT_HOST="https://your-cluster" \
  -e CROIT_API_TOKEN="your-token" \
  mcp-croit-ceph

# 使用本地OpenAPI规范运行（用于测试）
docker run -it --rm \
  -v $(pwd)/openapi.json:/config/openapi.json:ro \
  -e CROIT_HOST="http://dummy" \
  -e CROIT_API_TOKEN="dummy" \
  mcp-croit-ceph \
  --mode hybrid --openapi-file /config/openapi.json --no-permission-check

使用Docker Compose

version: '3.8'
services:
  mcp-croit-ceph:
    image: mcp-croit-ceph:latest
    environment:
      CROIT_HOST: "${CROIT_HOST}"
      CROIT_API_TOKEN: "${CROIT_API_TOKEN}"
      MCP_ARGS: "--mode hybrid"
    volumes:
      # 可选：使用本地OpenAPI规范
      - ./openapi.json:/config/openapi.json:ro

开发

⚠️ 重要提示

在进行开发工作之前，请始终激活虚拟环境：

source venv/bin/activate

测试工具数量

# 首先激活虚拟环境
source venv/bin/activate

# 检查每种模式下将生成的工具数量
for mode in hybrid base_only categories_only; do
  echo "$mode: $(python mcp-croit-ceph.py --mode $mode --openapi-file openapi.json --no-permission-check 2>&1 | grep -o 'Generated [0-9]* tools')"
done

调试日志

# 首先激活虚拟环境
source venv/bin/activate

# 启用调试日志
export LOG_LEVEL=DEBUG
python mcp-croit-ceph.py

使用本地OpenAPI规范进行测试

# 首先激活虚拟环境
source venv/bin/activate

# 使用测试脚本
./test-local.sh

# 或者手动测试不同模式
python mcp-croit-ceph.py --mode hybrid --openapi-file openapi.json --no-permission-check

运行测试

# 首先激活虚拟环境
source venv/bin/activate

# 运行时间戳修复测试
python test_timestamp_fix.py

# 运行其他测试（确保在虚拟环境中安装了依赖）
python test_actual_mcp.py

📄 许可证

本项目采用Apache 2.0许可证。

🔗 支持

如果你遇到与该MCP服务器相关的问题，请在本仓库中提交问题。如果你有Croit相关的问题，请联系Croit支持团队。

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client