Development Environment Setup

This guide will help you set up your development environment for the Home Assistant MCP Server.

Prerequisites

Required Software

Python 3.10 or higher
pip (Python package manager)
git
Docker (optional, for containerized development)
Node.js 18+ (for frontend development)

System Requirements

4GB RAM minimum
2 CPU cores minimum
10GB free disk space

Initial Setup

Clone the Repository

git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

Create Virtual Environment

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate  # Windows

Install Dependencies

pip install -r requirements.txt
pip install -r docs/requirements.txt  # for documentation

Development Tools

Code Editor Setup

We recommend using Visual Studio Code with these extensions: - Python - Docker - YAML - ESLint - Prettier

VS Code Settings

{
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true
}

Configuration

Create Local Config
```
cp config.example.yaml config.yaml
```

Set Environment Variables

cp .env.example .env
# Edit .env with your settings

Running Tests

Unit Tests

pytest tests/unit

Integration Tests

pytest tests/integration

Coverage Report

pytest --cov=src tests/

Docker Development

Build Container

docker build -t mcp-server-dev -f Dockerfile.dev .

Run Development Container

docker run -it --rm \
  -v $(pwd):/app \
  -p 8123:8123 \
  mcp-server-dev

Database Setup

Local Development Database

docker run -d \
  -p 5432:5432 \
  -e POSTGRES_USER=mcp \
  -e POSTGRES_PASSWORD=development \
  -e POSTGRES_DB=mcp_dev \
  postgres:14

Run Migrations

alembic upgrade head

Frontend Development

Install Node.js Dependencies
```
cd frontend
npm install
```
Start Development Server
```
npm run dev
```

Documentation

Build Documentation

mkdocs serve

View Documentation

Open http://localhost:8000 in your browser

Debugging

VS Code Launch Configuration

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: MCP Server",
      "type": "python",
      "request": "launch",
      "program": "src/main.py",
      "console": "integratedTerminal"
    }
  ]
}

Git Hooks

Install Pre-commit

pip install pre-commit
pre-commit install

Available Hooks

black (code formatting)
flake8 (linting)
isort (import sorting)
mypy (type checking)

Troubleshooting

Common Issues: 1. Port already in use - Check for running processes: lsof -i :8123 - Kill process if needed: kill -9 PID

Database connection issues
Verify PostgreSQL is running
Check connection settings in .env
Virtual environment problems
Delete and recreate: rm -rf .venv && python -m venv .venv
Reinstall dependencies