# WeMo MCP Server Configuration Guide

Complete guide to configuring the WeMo MCP Server for your environment.

## Table of Contents

- [Quick Start](#quick-start)
- [Configuration Methods](#configuration-methods)
- [Configuration Reference](#configuration-reference)
- [Example Configurations](#example-configurations)
- [Troubleshooting](#troubleshooting)

---

## Quick Start

### Method 1: Environment Variables (Recommended)

Quickest way to customize settings:

```bash
# Set your network subnet
export WEMO_MCP_DEFAULT_SUBNET="192.168.1.0/24"

# Extend cache lifetime to 2 hours
export WEMO_MCP_CACHE_TTL=7200

# Enable debug logging
export WEMO_MCP_LOG_LEVEL=DEBUG

# Start the server
uvx wemo-mcp-server
```

### Method 2: YAML Configuration File

For persistent configuration:

```bash
# Copy example config
cp config.example.yaml config.yaml

# Edit with your preferred editor
nano config.yaml

# Server will automatically load config.yaml if present
```

---

## Configuration Methods

The server loads configuration in this priority order (highest to lowest):

1. **Environment Variables** - Override everything
2. **YAML Config File** - Persistent settings
3. **Default Values** - Built-in defaults

### Environment Variables

All settings can be configured with the `WEMO_MCP_` prefix:

```bash
WEMO_MCP_DEFAULT_SUBNET=192.168.1.0/24
WEMO_MCP_SCAN_TIMEOUT=0.6
WEMO_MCP_MAX_WORKERS=60
WEMO_MCP_CACHE_ENABLED=true
WEMO_MCP_CACHE_FILE=~/.wemo_mcp_cache.json
WEMO_MCP_CACHE_TTL=3600
WEMO_MCP_LOG_LEVEL=INFO
```

**Load from .env file:**
```bash
cp .env.example .env
# Edit .env with your settings
source .env  # or use dotenv loader
```

### YAML Configuration File

The server looks for `config.yaml` in these locations (in order):

1. Current working directory: `./config.yaml`
2. User config directory: `~/.config/wemo-mcp/config.yaml`
3. System config directory: `/etc/wemo-mcp/config.yaml`

**Example config.yaml:**
```yaml
network:
  default_subnet: "192.168.1.0/24"
  scan_timeout: 0.6
  max_workers: 60
  retry_attempts: 3
  retry_delay: 0.5

cache:
  enabled: true
  file_path: "~/.wemo_mcp_cache.json"
  ttl_seconds: 3600

logging:
  level: "INFO"
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
```

---

## Configuration Reference

### Network Settings

#### `default_subnet`
- **Environment**: `WEMO_MCP_DEFAULT_SUBNET`
- **Default**: `192.168.1.0/24`
- **Format**: CIDR notation (e.g., `192.168.1.0/24`, `10.0.0.0/16`)
- **Description**: Network subnet to scan when not specified in scan_network call
- **Examples**:
  - `192.168.1.0/24` - Single /24 network (254 hosts)
  - `10.0.0.0/16` - Large /16 network (65,534 hosts)
  - `192.168.0.0/16` - Two /16 networks

#### `scan_timeout`
- **Environment**: `WEMO_MCP_SCAN_TIMEOUT`
- **Default**: `0.6`
- **Range**: `0.1` - `5.0` seconds
- **Description**: Connection timeout for port probing during network scan
- **Tips**:
  - Lower values = faster scan, may miss slow devices
  - Higher values = slower scan, catches all devices
  - Use `1.0` for large networks or WiFi devices
  - Use `0.4` for wired networks with fast devices

#### `max_workers`
- **Environment**: `WEMO_MCP_MAX_WORKERS`
- **Default**: `60`
- **Range**: `1` - `200`
- **Description**: Maximum concurrent threads for parallel scanning
- **Tips**:
  - Higher values = faster scan, may overwhelm network/router
  - Lower values = slower scan, gentler on network
  - Use `30-60` for home networks
  - Use `100-150` for enterprise networks
  - Reduce if experiencing network issues

#### `retry_attempts`
- **Environment**: `WEMO_MCP_RETRY_ATTEMPTS`
- **Default**: `3`
- **Range**: `1` - `10`
- **Description**: Number of retry attempts for device operations
- **Note**: Applied to control/status operations with exponential backoff

#### `retry_delay`
- **Environment**: `WEMO_MCP_RETRY_DELAY`
- **Default**: `0.5`
- **Range**: `0.1` - `5.0` seconds
- **Description**: Initial delay between retries (doubles each retry)

### Cache Settings

#### `enabled`
- **Environment**: `WEMO_MCP_CACHE_ENABLED`
- **Default**: `true`
- **Values**: `true`, `false`, `1`, `0`, `yes`, `no`
- **Description**: Enable/disable persistent device caching
- **Benefits**:
  - Faster startup (no scan needed)
  - Survives server restarts
  - Reduces network traffic

#### `file_path`
- **Environment**: `WEMO_MCP_CACHE_FILE`
- **Default**: `~/.wemo_mcp_cache.json`
- **Format**: Absolute or relative path
- **Description**: Location of cache file
- **Examples**:
  - `~/.wemo_mcp_cache.json` - User home directory
  - `/var/cache/wemo-mcp/devices.json` - System cache
  - `./cache.json` - Current directory

#### `ttl_seconds`
- **Environment**: `WEMO_MCP_CACHE_TTL`
- **Default**: `3600` (1 hour)
- **Range**: `0` - unlimited
- **Description**: Cache time-to-live in seconds
- **Special**: `0` = never expire
- **Examples**:
  - `300` - 5 minutes (frequent changes)
  - `3600` - 1 hour (balanced)
  - `7200` - 2 hours (stable network)
  - `86400` - 24 hours (rare changes)

### Logging Settings

#### `level`
- **Environment**: `WEMO_MCP_LOG_LEVEL`
- **Default**: `INFO`
- **Values**: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
- **Description**: Logging verbosity level
- **Recommendations**:
  - `DEBUG` - Development, troubleshooting
  - `INFO` - Production, normal operation
  - `WARNING` - Production, only warnings/errors
  - `ERROR` - Production, only errors

#### `format`
- **Environment**: `WEMO_MCP_LOG_FORMAT`
- **Default**: `%(asctime)s - %(name)s - %(levelname)s - %(message)s`
- **Description**: Python logging format string
- **Examples**:
  - `%(levelname)s: %(message)s` - Simple format
  - `%(asctime)s [%(levelname)s] %(message)s` - Compact format
  - `%(asctime)s - %(name)s - %(levelname)s - %(message)s` - Full format

---

## Example Configurations

### Home Network (Default)

Simple home network with standard settings:

```bash
export WEMO_MCP_DEFAULT_SUBNET="192.168.1.0/24"
export WEMO_MCP_SCAN_TIMEOUT=0.6
export WEMO_MCP_MAX_WORKERS=60
```

### Large Network

Enterprise or multi-subnet setup:

```bash
export WEMO_MCP_DEFAULT_SUBNET="10.0.0.0/16"
export WEMO_MCP_SCAN_TIMEOUT=1.0
export WEMO_MCP_MAX_WORKERS=100
export WEMO_MCP_CACHE_TTL=7200  # 2 hours
```

### IoT/Guest Network

Isolated network with limited devices:

```bash
export WEMO_MCP_DEFAULT_SUBNET="192.168.99.0/24"
export WEMO_MCP_SCAN_TIMEOUT=0.8
export WEMO_MCP_MAX_WORKERS=30
export WEMO_MCP_CACHE_TTL=3600
```

### Development/Debug

Maximum verbosity for troubleshooting:

```bash
export WEMO_MCP_DEFAULT_SUBNET="192.168.1.0/24"
export WEMO_MCP_LOG_LEVEL=DEBUG
export WEMO_MCP_CACHE_TTL=300  # 5 minutes
export WEMO_MCP_CACHE_ENABLED=false  # Disable for testing
```

### Docker/Container

Environment-based configuration for containers:

```dockerfile
# Dockerfile or docker-compose.yml
ENV WEMO_MCP_DEFAULT_SUBNET=192.168.1.0/24
ENV WEMO_MCP_CACHE_FILE=/var/cache/wemo/devices.json
ENV WEMO_MCP_CACHE_TTL=7200
ENV WEMO_MCP_LOG_LEVEL=INFO
```

### Multiple Subnets

Scan multiple networks (requires multiple scans):

```bash
# First subnet
claude chat "Scan 192.168.1.0/24 for devices"

# Second subnet
claude chat "Scan 10.0.0.0/16 for devices"

# Results are merged in cache
```

---

## Troubleshooting

### No Devices Found

**Problem**: `scan_network` finds 0 devices

**Solutions**:
1. **Check subnet**:
   ```bash
   # Find your subnet (macOS/Linux)
   ifconfig | grep "inet "
   # or
   ip addr show

   # Use correct subnet
   export WEMO_MCP_DEFAULT_SUBNET="your.subnet.0/24"
   ```

2. **Increase timeout**:
   ```bash
   export WEMO_MCP_SCAN_TIMEOUT=1.5
   ```

3. **Check network connectivity**:
   ```bash
   # Ping a known WeMo device
   ping 192.168.1.100
   ```

### Slow Scanning

**Problem**: Network scan takes too long

**Solutions**:
1. **Reduce workers** (if overwhelming network):
   ```bash
   export WEMO_MCP_MAX_WORKERS=30
   ```

2. **Reduce timeout** (if devices respond quickly):
   ```bash
   export WEMO_MCP_SCAN_TIMEOUT=0.4
   ```

3. **Use smaller subnet**:
   ```bash
   export WEMO_MCP_DEFAULT_SUBNET="192.168.1.0/28"  # Only 14 hosts
   ```

### Cache Issues

**Problem**: Devices not updating or cache corruption

**Solutions**:
1. **Clear cache manually**:
   ```bash
   claude chat "Clear the device cache"
   ```

2. **Delete cache file**:
   ```bash
   rm ~/.wemo_mcp_cache.json
   ```

3. **Disable caching**:
   ```bash
   export WEMO_MCP_CACHE_ENABLED=false
   ```

4. **Reduce TTL**:
   ```bash
   export WEMO_MCP_CACHE_TTL=300  # 5 minutes
   ```

### Device Control Failures

**Problem**: Devices found but control commands fail

**Solutions**:
1. **Enable debug logging**:
   ```bash
   export WEMO_MCP_LOG_LEVEL=DEBUG
   ```

2. **Check device responsiveness**:
   ```bash
   # Use WeMo app to control device
   # If WeMo app works, MCP should work
   ```

3. **Rescan network**:
   ```bash
   claude chat "Clear cache and scan for devices"
   ```

### Configuration Not Loading

**Problem**: Environment variables or config file ignored

**Solutions**:
1. **Verify environment variables**:
   ```bash
   env | grep WEMO_MCP
   ```

2. **Check config file location**:
   ```bash
   ls -la ~/.config/wemo-mcp/config.yaml
   ls -la ./config.yaml
   ```

3. **Use get_configuration tool**:
   ```bash
   claude chat "Show me the current configuration"
   ```

4. **Restart server/client** after configuration changes

---

## Advanced Topics

### Dynamic Configuration

Change settings without restarting:

```bash
# Use get_configuration to verify current settings
claude chat "Show current configuration"

# MCP tools respect current environment
# Export new values before next operation
export WEMO_MCP_SCAN_TIMEOUT=1.0
claude chat "Scan for devices"  # Uses new timeout
```

### Configuration Precedence

When multiple configuration sources exist:

```
Environment Variables  (highest priority)
    ↓
YAML Config File
    ↓
Default Values       (lowest priority)
```

Example:
- `config.yaml` sets `scan_timeout: 0.8`
- Environment has `WEMO_MCP_SCAN_TIMEOUT=1.0`
- **Result**: Uses `1.0` (environment wins)

### Sharing Configuration

**For teams:**
1. Commit `config.example.yaml` to git
2. Team members copy and customize locally
3. Add `config.yaml` to `.gitignore` (already done)

**For deployment:**
1. Use environment variables in production
2. Use config files for local development
3. Document settings in README or wiki

---

## Getting Help

If you're still having issues:

1. **Enable debug logging**:
   ```bash
   export WEMO_MCP_LOG_LEVEL=DEBUG
   ```

2. **Check logs** for error messages

3. **Verify settings**:
   ```bash
   claude chat "Show configuration"
   ```

4. **Test basic connectivity**:
   ```bash
   claude chat "Scan for devices"
   ```

5. **Open an issue** on GitHub with:
   - Configuration (sanitize IP addresses)
   - Debug logs
   - Network setup description
   - Expected vs actual behavior

---

## See Also

- [README.md](README.md) - Main documentation
- [config.example.yaml](config.example.yaml) - Complete YAML config template
- [.env.example](.env.example) - Environment variable template
- [CHANGELOG.md](CHANGELOG.md) - Version history and changes