cycloid-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Cycloid MCP Server is a Model Context Protocol (MCP) server that bridges AI assistants with the Cycloid infrastructure automation platform. It wraps the Cycloid CLI (cy binary) to expose blueprints, stacks, service catalogs, pipelines, and events as MCP tools and resources over HTTP.

Common Commands

make setup              # First-time dev environment setup (installs uv + deps)
make dev-server         # Run development server
make test               # Run all tests with pytest
make type-check         # Pyright strict mode type checking
make lint               # flake8 linting
make format             # Format with black + isort
make quality-check      # All checks: test + type-check + lint
make simulate-ci        # Full local CI simulation (validates Python 3.13, runs all checks)
make build              # Build Docker image
make prod-server        # Run production Docker container

Run a single test file:

uv run pytest tests/test_stack_component.py -v

Architecture

Request Flow

HTTP Request → FastMCP 3.0 (Starlette/Uvicorn) → @tool/@resource function
  → CLIMixin (via Depends) → Cycloid CLI binary → Cycloid API

The server is HTTP-only and multi-tenant: org and API key come from request headers (X-CY-ORG, X-CY-API-KEY), not environment variables.

Component System (FastMCP 3.0)

Components are plain async functions in src/components/, auto-discovered by FileSystemProvider. No registry, no base classes — just @tool() and @resource() decorators with Depends(get_cli) for CLI injection.

Each component file contains:

• Private helper functions (prefixed _)
• @tool decorated async functions — MCP tools
• @resource decorated async functions — MCP resources

Current component files: catalogs.py, events.py, pipelines.py, stacks.py (includes elicitation), stackforms.py.