{
  "markdown": "# MCP Croit Ceph\n\n> AI-powered management for Croit Ceph clusters via the Model Context Protocol (MCP)\n\nConnect your AI assistant (like Claude) directly to your Croit Ceph cluster for intelligent cluster management, troubleshooting, and monitoring.\n\n## What is this?\n\nAn MCP server that gives AI assistants access to your Croit Ceph cluster's REST API. Ask your AI to:\n- \"Show me all pools with errors\"\n- \"List OSDs on server node-5\"\n- \"Search logs for slow requests in the last hour\"\n- \"What's the cluster health status?\"\n\nThe AI can then interact with your cluster through natural language.\n\n## Key Features\n\n### 🚀 Smart & Efficient\n- **Automatic token optimization** - Responses optimized to save 80-95% on AI token costs\n- **Field selection** - Request only the data you need (e.g., just id + name)\n- **Built-in filtering** - grep-like search without multiple API calls\n- **Intelligent summaries** - Large datasets get smart summaries with drill-down capability\n\n### 🔍 Advanced Log Search\n- Native VictoriaLogs integration for powerful log analysis\n- Natural language queries: \"Find OSD failures in the last 24 hours\"\n- Pattern detection and anomaly identification\n- Pre-built debug templates for common issues\n\n### 🛡️ Production Ready\n- Role-based access control (ADMIN vs VIEWER)\n- Automatic API discovery from your cluster\n- Docker support with included OpenAPI spec\n- Comprehensive error handling\n\n## Quick Start\n\n### Using Docker (Recommended)\n\n```bash\ndocker run --rm -i \\\n  -e CROIT_HOST=\"https://your-cluster.com\" \\\n  -e CROIT_API_TOKEN=\"your-api-token\" \\\n  croit/mcp-croit-ceph:latest\n```\n\n### With Claude Desktop\n\nAdd to `~/.config/claude/claude_desktop_config.json`:\n\n**Basic configuration** (fetches OpenAPI spec on startup):\n```json\n{\n  \"mcpServers\": {\n    \"croit-ceph\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"--rm\", \"-i\",\n        \"-e\", \"CROIT_HOST=http://your-cluster.croit.io:8080\",\n        \"-e\", \"CROIT_API_TOKEN=your-api-token-here\",\n        \"croit/mcp-croit-ceph:latest\"\n      ]\n    }\n  }\n}\n```\n\n**Optimized configuration** (recommended - 2s startup instead of 5s):\n```json\n{\n  \"mcpServers\": {\n    \"croit-ceph\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"--rm\", \"-i\",\n        \"-v\", \"/absolute/path/to/openapi.json:/config/openapi.json:ro\",\n        \"-e\", \"CROIT_HOST=http://your-cluster.croit.io:8080\",\n        \"-e\", \"CROIT_API_TOKEN=your-api-token-here\",\n        \"-e\", \"OPENAPI_FILE=/config/openapi.json\",\n        \"croit/mcp-croit-ceph:latest\"\n      ]\n    }\n  }\n}\n```\n\n**With debug logging:**\n```json\n{\n  \"mcpServers\": {\n    \"croit-ceph\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"--rm\", \"-i\",\n        \"-e\", \"CROIT_HOST=http://your-cluster.croit.io:8080\",\n        \"-e\", \"CROIT_API_TOKEN=your-api-token-here\",\n        \"-e\", \"LOG_LEVEL=DEBUG\",\n        \"croit/mcp-croit-ceph:latest\"\n      ]\n    }\n  }\n}\n```\n\n**Note:** Volume mounts require absolute paths (not `~/`). To download the OpenAPI spec:\n```bash\ncurl -H \"Authorization: Bearer YOUR_TOKEN\" \\\n     http://your-cluster.croit.io:8080/api/swagger.json > openapi.json\n```\n\nRestart Claude Desktop after changing the configuration.\n\n## Configuration\n\n### Required Environment Variables\n\n```bash\nCROIT_HOST=\"https://your-cluster.com\"      # Your Croit cluster URL\nCROIT_API_TOKEN=\"your-api-token\"           # API token from Croit\n```\n\n### Optional Environment Variables\n\n```bash\n# Use local OpenAPI spec for faster startup (2s vs 5s)\nOPENAPI_FILE=\"/config/openapi.json\"\n\n# Use bundled spec (no external fetch, for offline/dev)\nUSE_INCLUDED_API_SPEC=\"true\"\n\n# Logging verbosity: DEBUG, INFO, WARNING, ERROR\nLOG_LEVEL=\"INFO\"\n\n# Pass additional CLI arguments\nMCP_ARGS=\"--no-permission-check --max-category-tools 5\"\n```\n\nSee `.env.example` for docker usage template.\n\n### Getting an API Token\n\n1. Log into your Croit cluster web interface\n2. Go to **Settings** → **API Tokens**\n3. Create a new token with appropriate permissions\n4. Copy the token and use it in your configuration\n\n## Example AI Conversations\n\n**Check cluster health:**\n```\nYou: \"What's the current cluster status?\"\nAI: Calls list_endpoints → Finds status endpoint → Returns health summary\n```\n\n**Find problems:**\n```\nYou: \"Show me all pools with errors\"\nAI: Calls /pools with fields=[\"id\",\"name\",\"status\"] and filter for errors\n    Returns only the 3 pools with issues (instead of all 100 pools)\n```\n\n**Debug issues:**\n```\nYou: \"Search logs for OSD failures in the last hour\"\nAI: Uses croit_log_search with smart query parsing\n    Returns summary + drill-down capability for details\n```\n\n**Capacity planning:**\n```\nYou: \"Which pools are over 80% full?\"\nAI: Gets pools → Filters by usage → Returns list with recommendations\n```\n\n## Features in Detail\n\n### Token Optimization\n\nThe server automatically reduces AI token consumption:\n\n| Without Optimization | With Optimization | Savings |\n|---------------------|-------------------|---------|\n| 100 pools, all fields → 4,000 tokens | 100 pools, id+name → 300 tokens | **92%** |\n| 500 OSDs, full data → 15,000 tokens | Smart summary → 1,000 tokens | **93%** |\n\n**How it works:**\n1. **Field Selection**: Request only needed fields\n2. **Smart Summaries**: Large datasets get summaries with drill-down\n3. **Caching**: Repeated requests use cached data\n4. **Auto-limiting**: Sensible defaults prevent token explosions\n\n### Available Tools\n\nThe AI has access to these tools:\n\n**Core Tools:**\n- `list_endpoints` - Discover available API endpoints\n- `call_endpoint` - Make API calls with optimization\n- `search_last_result` - Drill down into large responses\n\n**Category Tools** (auto-generated):\n- `manage_services` - Ceph services\n- `manage_pools` - Storage pools\n- `manage_servers` - Cluster servers\n- `manage_s3` - S3 buckets\n- And more...\n\n**Log Search:**\n- `croit_log_search` - Advanced log analysis\n- `croit_log_check` - Quick log condition checks\n\n## Advanced Usage\n\n### Local Development\n\n```bash\n# Clone repository\ngit clone https://github.com/croit/mcp-croit-ceph.git\ncd mcp-croit-ceph\n\n# Create virtual environment\npython3 -m venv venv\nsource venv/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run directly\nexport CROIT_HOST=\"https://your-cluster.com\"\nexport CROIT_API_TOKEN=\"your-token\"\npython mcp-croit-ceph.py\n```\n\n### Using Local OpenAPI Spec\n\nFor faster startup or offline development:\n\n```bash\n# Download spec from your cluster\ncurl -H \"Authorization: Bearer $CROIT_API_TOKEN\" \\\n     https://your-cluster/api/swagger.json > openapi.json\n\n# Use local spec\npython mcp-croit-ceph.py --openapi-file openapi.json\n```\n\n### Command Line Options\n\n```bash\npython mcp-croit-ceph.py \\\n  --openapi-file openapi.json \\      # Use local OpenAPI spec\n  --no-permission-check \\            # Skip role check (faster)\n  --max-category-tools 5             # Limit category tools\n```\n\n## Permissions & Security\n\nThe server respects your API token's role:\n\n- **ADMIN**: Full access to all operations\n- **VIEWER**: Read-only access (no create/delete/update)\n- **Invalid token**: Server exits with error\n\nAdmin-only categories: `maintenance`, `servers`, `config`, `hooks`\n\n## Troubleshooting\n\n**Token not working:**\n- Verify token in Croit web interface\n- Check token hasn't expired\n- Ensure token has correct permissions\n\n**Connection issues:**\n- Verify `CROIT_HOST` is correct (include https://)\n- Check network connectivity to cluster\n- Verify firewall allows connection\n\n**No tools showing:**\n- Check Docker logs for errors\n- Verify OpenAPI spec is valid\n- Try `--no-permission-check` to test\n\n**Enable debug logging:**\n```bash\nexport LOG_LEVEL=DEBUG\npython mcp-croit-ceph.py\n```\n\n## Documentation\n\n- **[Architecture](ARCHITECTURE.md)** - Technical architecture and design\n- **[Token Optimization](docs/TOKEN_OPTIMIZATION.md)** - How optimization works\n- **[Claude Integration](CLAUDE.md)** - Tips for using with Claude\n\n## Contributing\n\nContributions welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run `black` formatter on Python files\n5. Submit a pull request\n\n## License\n\nSee [LICENSE](LICENSE) for details\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/croit/mcp-croit-ceph/issues)\n- **Croit Support**: For cluster-specific questions\n- **MCP Protocol**: [Model Context Protocol Documentation](https://modelcontextprotocol.io)\n\n---\n\nMade with ❤️  for the Ceph community\n",
  "bytes": 8389,
  "sha": "43c8ae02a350dbc48da0f2051ad8425d64be916cb898663de4acb36c9fa26893",
  "repo_slug": "croit/mcp-croit-ceph",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_croit_mcp_croit_ceph_fa124073/readme"
}