Contributing to ha-mcp

Thank you for your interest in contributing!

Quick Start

  1. 1 Fork and clone the repository
  2. 2
    Install: 
    uv sync --group dev
  3. 3
    Test: (requires Docker) 
    uv run pytest tests/src/e2e/ -v
  4. 4 Make changes and commit
  5. 5 Open Pull Request

Development

Setup

cp .env.example .env    # Edit with your HA details
uv sync --group dev

Code Quality

uv run ruff format src/ tests/     # Format
uv run ruff check --fix src/ tests/ # Lint
uv run mypy src/                   # Type check

Testing

Tests use Docker containers via testcontainers. No manual setup needed.

# Run all E2E tests
HAMCP_ENV_FILE=tests/.env.test uv run pytest tests/src/e2e/ -v

# Run specific test file
uv run pytest tests/src/e2e/workflows/automation/test_lifecycle.py -v

See tests/README.md for detailed testing documentation.

Guidelines

💻 Code

Follow existing patterns, add type hints, test new features

📄 Docs

Update README.md for user-facing changes

📦 PRs

Use the template, ensure tests pass

Need Help?

Thank you for contributing!

Every contribution helps make ha-mcp better for the community.

View on GitHub