Initial commit: Javis project

homey-mcp/UBUNTU_SETUP.md

@@ -0,0 +1,137 @@
+# 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"