# Homey MCP Server - Ubuntu Setup Guide

## Quick Start

### 1. Run the setup script
```bash
cd homey-mcp
chmod +x setup-ubuntu.sh run.sh run-lan.sh
./setup-ubuntu.sh
```

### 2. Configure your credentials
Edit the `.env` file with your Homey Pro credentials:
```bash
nano .env
```

Required fields:
- `HOMEY_TOKEN` - Your Homey Pro personal access token
- `HOMEY_HOST` - Your Homey Pro hub IP (e.g., `192.168.1.100`)
- `HOMEY_SCHEME` / `HOMEY_PORT` - Local API protocol and port

Optional for LAN mode:
- `HOMEY_MCP_AUTH_MODE` - `none` for trusted-LAN compatibility, or `bearer`
- `HOMEY_MCP_AUTH_TOKEN` - Protects REST and, in `bearer` mode, MCP requests
- `HOMEY_MCP_ADVERTISED_HOST` - Set this to your server's LAN IP (e.g., `10.10.10.50`). Required if using `HOMEY_MCP_HOST=0.0.0.0`.

### 3. Start the server

**For remote Odysseus client (LAN mode):**
```bash
./run-lan.sh
```

**For local stdio mode (Javis integration):**
```bash
./run.sh
```

## Manual Installation

If you prefer to set up manually:

```bash
# Install Python (if not installed)
sudo apt install python3.10 python3.venv build-essential libffi-dev libssl-dev

# Create virtual environment
cd homey-mcp
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -e .
pip install uvicorn

# Configure
cp .env.example .env
nano .env  # Edit with your credentials

# Run
HOMEY_MCP_TRANSPORT=streamable-http HOMEY_MCP_HOST=0.0.0.0 HOMEY_MCP_PORT=8080 \
    python -m homey_mcp
```

## Persistent Operation with systemd

Install the service file for automatic startup:

```bash
# Copy service file
sudo cp homey-mcp.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable and start (replace $USER with your username)
sudo systemctl enable --now homey-mcp@$USER.service

# Check status
sudo journalctl -u homey-mcp@$USER.service -f
```

## Connecting Odysseus

To connect Odysseus as an MCP client, use the streamable-http transport:

1. **Important:** Before starting the server, set `HOMEY_MCP_ADVERTISED_HOST` in `.env` to your Ubuntu server's LAN IP address (e.g., `10.10.10.50`). This is required for MCP Host header validation.
2. Ensure homey-mcp is running on port 8080 (or your configured port)
3. Configure Odysseus with the MCP endpoint:
   ```
   URL: http://<YOUR_UBUNTU_IP>:8080/mcp
   Transport: streamable-http
   Authentication: none
   ```

If you see a "421 Misdirected Request" error, your `HOMEY_MCP_ADVERTISED_HOST` is not set correctly; it must match the IP that Odysseus uses to connect.

Use `HOMEY_MCP_AUTH_MODE=none` only on a trusted, firewall-restricted LAN.
This avoids an OAuth discovery flow, which homey-mcp does not implement. If
Odysseus supports a manually configured static Authorization header, you may
instead set `HOMEY_MCP_AUTH_MODE=bearer` and configure the value of
`HOMEY_MCP_AUTH_TOKEN` as its bearer token.

For Odysseus OpenAPI/`app_api` integration, import
`http://<YOUR_UBUNTU_IP>:8080/openapi.json` and configure
`HOMEY_MCP_AUTH_TOKEN` as a bearer token. REST routes remain protected even
when MCP authentication is disabled.

## Troubleshooting

### Virtual environment issues
```bash
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

### Port already in use
```bash
# Check what's using the port
sudo lsof -i :8080

# Use a different port
HOMEY_MCP_PORT=8081 ./run-lan.sh
```

### Permission denied
```bash
chmod +x run.sh run-lan.sh setup-ubuntu.sh
```

### Check logs
```bash
sudo journalctl -u homey-mcp@$USER.service -f --since "1 hour ago"