{
  "markdown": "# Cycloid MCP Server\n\n[![PR Quality Check](https://github.com/cycloidio/cycloid-mcp-server/workflows/PR%20Quality%20Check/badge.svg)](https://github.com/cycloidio/cycloid-mcp-server/actions/workflows/pr-quality-check.yml)\n\nA Model Context Protocol (MCP) server that provides seamless integration with the Cycloid platform, enabling AI assistants to interact with Cycloid's infrastructure management capabilities through natural language.\n\n## Overview\n\nThe Cycloid MCP Server bridges the gap between AI assistants and Cycloid's powerful infrastructure automation platform. It enables users to:\n\n- **Discover and explore** available blueprints and service catalogs\n- **Create and manage** infrastructure stacks using Cycloid's blueprints\n- **Interact naturally** with complex infrastructure workflows through AI assistants\n- **Leverage Cycloid's expertise** in infrastructure as code and automation\n\n\n## Available Tools\n\n- **`CYCLOID_BLUEPRINT_LIST`**: List all available blueprints with their details\n- **`CYCLOID_BLUEPRINT_STACK_CREATE`**: Create stacks from blueprints with interactive elicitation\n- **`CYCLOID_STACKFORMS_VALIDATE`**: Validate StackForms configuration files\n- **`CYCLOID_CATALOG_REPO_LIST`**: List service catalog repositories\n- **`CYCLOID_EVENT_LIST`**: List organization events with optional filters (`begin`, `end`, `severity`, `type`)\n- **`CYCLOID_PIPELINE_LIST`**: List all pipelines from Cycloid\n\n## Available Resources\n\n- **`cycloid://blueprints`**: Access to blueprint information\n- **`cycloid://service-catalogs-repositories`**: Access to service catalog repositories information\n- **`cycloid://events`**: Access to recent organization events as JSON\n- **`cycloid://pipelines`**: Access to pipeline information\n\n### Event Filters\n- **begin/end**: Unix timestamps (strings) delimiting the time window\n- **severity**: One or more of `info`, `warn`, `err`, `crit`\n- **type**: One or more of `Cycloid`, `AWS`, `Monitoring`, `Custom`\n\n## Architecture\n\nThe server uses a dynamic component registration system based on FastMCP's MCPMixin:\n\n- **Automatic Discovery**: Components are automatically discovered from `src/components/`\n- **File-based Organization**: Components are organized by feature (`catalogs/`, `stacks/`)\n- **Standard Patterns**: Each component follows the pattern `*_tools.py`, `*_resources.py`, `*_handlers.py`, `*_prompts.py`\n- **MCPMixin Integration**: Uses FastMCP's built-in `register_all()` method for proper tool/resource registration\n\n## HTTP Transport\n\nThe Cycloid MCP Server runs as a web service using HTTP transport. Organization and API key are provided via HTTP headers (`X-CY-ORG` and `X-CY-API-KEY`) for each request, enabling multi-tenant usage.\n\n**Usage:** `python server.py`\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.12 or higher\n- [uv](https://github.com/astral-sh/uv) package manager (recommended)\n- Docker (for production deployment)\n- Valid Cycloid API credentials\n\n### Development Setup\n\n```bash\n# Clone and setup\ngit clone <repository-url>\ncd cycloid-mcp-server\nmake setup\n\n# Run development server\nmake dev-server\n```\n\n### Production Setup\n\n#### Using Pre-built Docker Images\n\nThe project provides pre-built Docker images via Docker Hub:\n\n```bash\n# Pull the latest image\ndocker pull cycloid/cycloid-mcp-server:latest\n\n# Run the server\ndocker run -p 8010:8010 cycloid/cycloid-mcp-server:latest\n```\n\n#### Building Locally\n\n```bash\n# Build Docker image\nmake build\n\n# Run production server\nmake prod-server\n```\n\n## MCP Configuration\n\nFor detailed MCP server configuration examples, see [mcp-examples.md](mcp-examples.md).\n\n## Available Commands\n\n```bash\n# Development Environment\nmake setup          # Setup development environment with uv\nmake install        # Install dependencies\nmake help           # Show all available commands\nmake validate-env   # Validate local environment matches CI\n\n# Development Server\nmake dev-server     # Run development server using Python virtual environment\n\n# HTTP Server\npython server.py  # Run HTTP server\n\n# Production\nmake build          # Build Docker image\nmake prod-server    # Run production server using Docker\n\n# Testing and Quality\nmake test           # Run all tests\nmake type-check     # Run pyright type checking\nmake lint           # Run PEP 8 linting with flake8\nmake format         # Format code with black and isort\nmake quality-check  # Run all quality checks (tests + type checking + linting)\nmake simulate-ci    # Validate environment and run quality checks\n\n# Cleanup\nmake clean          # Clean up development artifacts\nmake clean-docker   # Clean up Docker artifacts\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n",
  "bytes": 4786,
  "sha": "30a5643cfd97b1d7f14a3fd948285d51cc4a184702d27d12c05d037d63b33085",
  "repo_slug": "cycloidio/cycloid-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_cycloid_mcp_server_84179730/readme"
}