Skip to content

# 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

1. Clone the Repository

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

2. Create Virtual Environment

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

3. 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

1. Create Local Config

       cp config.example.yaml config.yaml

2. 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

1. Install Node.js Dependencies

       cd frontend
       npm install

2. 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`

1. Database connection issues
2. Verify PostgreSQL is running

3. Check connection settings in .env

4. Virtual environment problems

5. Delete and recreate: `rm -rf .venv && python -m venv .venv`
6. Reinstall dependencies

## Next Steps

1. Review the Architecture Guide
2. Check Contributing Guidelines
3. Start with Simple Issues

February 6, 2025
February 6, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings