cloud-vm-mcp-py: Instructions file for Codex

AGENTS.md

MCP server for managing VMs across cloud providers (AWS, Azure). Python 3.10+, uv package manager, FastMCP framework, Pydantic models.

Build & Run

uv sync                          # Install all dependencies
uv run vm-mcp                    # Start the MCP server
uv run python cli.py list        # CLI: list VMs

Lint, Format, Type Check

uv run ruff check .              # Lint (auto-fixes with --fix by default, fix=true in config)
uv run ruff format .             # Format
uv run ty check .                # Type check (Astral's ty, scoped to vm_mcp/)

Pre-commit hooks run uv-lock sync and ty check automatically.

Tests

uv run pytest tests/ -v                                          # All tests
uv run pytest tests/test_config.py -v                            # Single file
uv run pytest tests/test_config.py::TestConfigLoader -v          # Single class
uv run pytest tests/test_config.py::TestConfigLoader::test_load_valid_config -v  # Single test
uv run pytest -k "test_load_valid" -v                            # By name pattern
uv run pytest tests/ --cov=vm_mcp --cov-report=html              # With coverage

Test stack: pytest + pytest-asyncio + pytest-mock. Async tests use @pytest.mark.asyncio. Tests are class-based (e.g., class TestConfigLoader:). Fixtures in tests/conftest.py.

Project Structure

vm_mcp/
├── __init__.py          # Exports main() and mcp
├── __main__.py          # python -m vm_mcp entry point
├── config.py            # ConfigLoader with file watching (hot-reload, watchdog)
├── mcp.py               # FastMCP server, all MCP tool definitions
├── model/
│   ├── credentials.py   # AWS/Azure credential Pydantic models
│   └── vm.py            # VMState, VMInfo, VMDetails, VMError models
└── providers/
    ├── base.py           # Abstract BaseProvider (ABC)
    ├── aws.py            # AWS EC2 provider
    ├── azure.py          # Azure Compute provider
    └── registry.py       # Provider factory/lookup