MCP Croit Ceph

An MCP (Model Context Protocol) server for interacting with Croit Ceph clusters through their REST API.

Current Status

• 580 total API endpoints
• 575 endpoints with x-llm-hints (99.1% coverage)
• 100% endpoints have summaries
• 13 tools in hybrid mode (97% reduction)
• Full support for all x-llm-hints fields

Features

Automatic Token Optimization

The MCP server automatically optimizes responses to reduce token consumption:

• Auto-limits: Adds default limits (10-100 items) to list operations
• Smart truncation: Large responses automatically truncated with metadata
• Optimization hints: Tool descriptions include token-saving tips
• Response metadata: Truncated responses include info on how to get more data

Example: Instead of 500 services (50,000 tokens), you get 25 services + metadata (2,500 tokens)

Built-in Filtering (grep-like search)

Filter API responses locally without multiple calls:

• Field filtering: _filter_status='error' - exact match
• Regex patterns: _filter_name='~ceph.*' - pattern matching
• Numeric comparisons: _filter_size='>1000' - greater than
• Text search: _filter__text='timeout' - search all text fields
• Field existence: _filter__has='error_message' - has field
• Multiple values: _filter_status=['error','warning'] - OR logic

Example: Find errors in 500 services with one call:

_filter_status='error' → Returns only 5 error services (99% token savings)

Hybrid Mode (Default) - 97% Fewer Tools!

The new hybrid mode reduces the tool count from 580 individual endpoint tools to just 13 tools total:

• 3 Base tools for full API access
• 10 Category tools for common operations (services, maintenance, s3, pools, etc.)

This dramatic reduction improves:

• LLM performance and response times
• Tool discovery and usability
• Memory efficiency
• Startup time

Tool Generation Modes

1. hybrid (default): Combines base tools with category tools for optimal balance
2. base_only: Only 3 base tools for minimal footprint
3. categories_only: Only category tools for simplified operations
4. endpoints_as_tools: Legacy mode with 580 individual tools (one per API endpoint)

Dynamic Features

• Automatic API Discovery: Fetches OpenAPI spec from your Croit cluster
• Permission-Based Filtering: Role-based tool filtering (ADMIN vs VIEWER)
• Full x-llm-hints Support: 575+ endpoints with AI optimization hints
• Local OpenAPI Support: Use a local OpenAPI spec file for testing/development
• Schema Resolution: Handles $ref references automatically

Advanced x-llm-hints Integration

The MCP server fully integrates Croit's x-llm-hints into tool descriptions for optimal LLM guidance:

What x-llm-hints provide:

• Purpose: Clear description of what each endpoint does
• Usage examples: Common use cases and workflow guidance
• Failure modes: Expected errors and how to handle them
• Rate limits: API throttling information for efficient usage
• Retry strategies: How to handle transient failures
• Poll intervals: Recommended refresh rates for live data
• Cache hints: Response caching strategies
• Related endpoints: Cross-references for complex workflows

Examples of integrated hints:

manage_cluster tool:
Purpose: Bootstrap a brand-new Ceph cluster using the selected MON disk and IP address.

Common usage:
• Invoke immediately after fetching candidates from GET /cluster/create/mons
• Monitor the returned ManagedTask via /tasks/{id} until bootstrap completes

Failure modes:
• 400: Validate disk/server eligibility via GET /cluster/create/mons
• 409: If concurrent bootstrap is in progress, wait for existing task

Rate limits: 60/300s, 30/300s
Retry strategy: manual_retry, exponential_backoff

Benefits for LLMs:

• Context-aware operations: LLMs understand when and how to use each tool
• Error handling: Proactive guidance on handling API errors
• Performance optimization: Built-in rate limiting and caching awareness
• Workflow intelligence: Understanding of multi-step operations

Installation

⚠️ IMPORTANT: This project requires a virtual environment due to system-managed Python environments.

# Clone the repository
git clone https://github.com/croit/mcp-croit-ceph.git
cd mcp-croit-ceph

# Create and activate virtual environment (REQUIRED)
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install dependencies in virtual environment
pip install -r requirements.txt

Note: Always activate the virtual environment (source venv/bin/activate) before running any Python commands or tests.

Configuration

Set up your environment variables:

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

Or use a config file at /config/config.json:

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

Usage

Basic Usage (Hybrid Mode)

# Activate virtual environment first (REQUIRED)
source venv/bin/activate

# Default hybrid mode with permission checking
python mcp-croit-ceph.py

Advanced Options

# Activate virtual environment first (REQUIRED)
source venv/bin/activate

# Use local OpenAPI spec file
python mcp-croit-ceph.py --openapi-file openapi.json

# Skip permission checking (faster startup)
python mcp-croit-ceph.py --no-permission-check

# Use only base tools (minimal mode)
python mcp-croit-ceph.py --mode base_only

# Use only category tools
python mcp-croit-ceph.py --mode categories_only

# Legacy mode with all 580 endpoint tools (not recommended)
python mcp-croit-ceph.py --mode endpoints_as_tools

# Customize category tool limits
python mcp-croit-ceph.py --max-category-tools 5

Tool Modes Explained

Hybrid Mode (Recommended)

Provides the best balance with ~13 tools:

Base Tools:

• list_endpoints - Search and filter API endpoints
• call_endpoint - Direct API calls to any endpoint
• get_schema - Resolve schema references

Category Tools (top 10):

• manage_services - Ceph services operations
• manage_maintenance - Maintenance tasks
• manage_s3 - S3 bucket management
• manage_pools - Storage pool operations
• manage_servers - Server management
• And more...

Each category tool supports actions like: list, get, create, update, delete

Base Only Mode

Minimal setup with just 3 tools for full API access:

• list_api_endpoints - Discover available endpoints
• call_api_endpoint - Make API calls
• get_reference_schema - Resolve schemas

Categories Only Mode

Simplified interface with only category tools, no base tools.

Endpoints as Tools Mode (Legacy)

Creates 580 individual tools (one per API endpoint). Not recommended due to:

• Performance overhead
• Difficult tool discovery
• MCP client limitations

Permission-Based Filtering

The server intelligently filters tools based on the API token's role:

1. Automatic Role Detection: Fetches roles via /auth/token-info endpoint
2. Role-Based Access:
   • ADMIN role: Full access to all categories
   • VIEWER/other roles: All categories except admin-only operations
   • Invalid token: Server will exit with error (no access)

Category Access Control

Admin-Only Categories:

• maintenance, servers, ipmi - System management
• config, hooks, change-requests - Configuration changes
• config-templates - Template management

All Other Categories are accessible to VIEWER roles for read operations:

• cluster, status, stats - Monitoring
• logs, disks, services - Information viewing
• s3, cephfs, rbds, pools - Storage info
• authentication, images, daos - Read operations
• And all others not listed as admin-only

This role-based approach is fast and ensures users only see tools they can actually use.

Using Local OpenAPI Spec

For offline development or testing:

# Download spec from your cluster
curl -H "Authorization: Bearer $CROIT_API_TOKEN" \
     https://your-cluster/api/swagger.json > openapi.json

# Use the local file
python mcp-croit-ceph.py --openapi-file openapi.json

MCP Integration

With Claude Desktop

Add to your Claude Desktop config:

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

With Other MCP Clients

The server implements the standard MCP protocol and works with any compatible client.

Command Line Arguments

Argument	Description	Default
--mode	Tool generation mode	hybrid
--openapi-file	Local OpenAPI spec file	None (fetch from server)
--no-permission-check	Skip permission checking	False (check enabled)
--max-category-tools	Max category tools to generate	10
--no-resolve-references	Don't resolve $ref in spec	False (resolve enabled)
--offer-whole-spec	Include full spec in list tool	False

Docker Usage

Build and Run with Docker

# Build the Docker image
docker build -t mcp-croit-ceph .

# Run with environment variables
docker run -it --rm \
  -e CROIT_HOST="https://your-cluster" \
  -e CROIT_API_TOKEN="your-token" \
  mcp-croit-ceph

# Run with local OpenAPI spec (for testing)
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:
      # Optional: Use local OpenAPI spec
      - ./openapi.json:/config/openapi.json:ro

Development

⚠️ Remember: Always activate the virtual environment before development work:

source venv/bin/activate

Testing Tool Count

# Activate virtual environment first
source venv/bin/activate

# Check how many tools will be generated in each mode
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

Debug Logging

# Activate virtual environment first
source venv/bin/activate

# Enable debug logging
export LOG_LEVEL=DEBUG
python mcp-croit-ceph.py

Testing with Local OpenAPI Spec

# Activate virtual environment first
source venv/bin/activate

# Use the test script
./test-local.sh

# Or manually test different modes
python mcp-croit-ceph.py --mode hybrid --openapi-file openapi.json --no-permission-check

Running Tests

# Activate virtual environment first
source venv/bin/activate

# Run timestamp fix test
python test_timestamp_fix.py

# Run other tests (ensure dependencies are installed in venv)
python test_actual_mcp.py

License

Apache 2.0

Support

For issues specific to this MCP server, please open an issue in this repository. For Croit-specific questions, contact Croit support.