# Javis Slave MCP

MCP (Model Context Protocol) server for controlling local Javis Slave devices.
Slaves can run on Windows tablets or Linux boards (Raspberry Pi, see
[javis-slave/RASPBERRY_PI.md](../javis-slave/RASPBERRY_PI.md)); the control
endpoints are identical on both.

## Features

- **Status Monitoring**: Check device status, audio state, mic level, muted state
- **Device Info**: Get device configuration (sample rate, audio devices, wake word model)
- **Network Discovery**: Query the master for the IP of any slave, or list all connected slaves
- **Microphone Control**: Mute/unmute/toggle microphone on slave devices
- **Audio Engine Recovery**: Restart audio engine (stop + start) when needed
- **Volume Control**: Get/set/increase/decrease master volume, mute/unmute output
- **Brightness Control**: Get/set/increase/decrease display brightness
- **Power Control**: Sleep / shutdown / restart / cancel shutdown

## Configuration

### Environment Variables

```bash
# Comma-separated list of device_id=host:port
export JAVIS_SLAVE_DEVICES="device1=192.168.1.100:8766,device2=192.168.1.101:8766"
```

### Config File

Create `~/.javis/slave_mcp_config.json`:

```json
{
  "slaves": {
    "bedroom": {
      "host": "192.168.1.100",
      "port": 8766
    },
    "kitchen": {
      "host": "192.168.1.101",
      "port": 8766
    }
  }
}
```

### Default

If no configuration is provided, the server defaults to `localhost:8766` (for local development).

## Installation

```bash
pip install -e .
```

## Usage

Run the server:

```bash
python -m javis_slave_mcp
```

Or with a custom config:

```bash
export JAVIS_SLAVE_DEVICES="my_device=192.168.1.100:8766"
python -m javis_slave_mcp
```

## MCP Tools

All tools take `device_id` (default `"localhost"`) unless noted otherwise.

**Status & discovery**

- `slave_list_devices()` — List all configured slave devices
- `slave_get_status(device_id)` — Get current device status (incl. `muted`)
- `slave_get_info(device_id)` — Get device information
- `slave_get_ip_address(device_id)` — IP of the slave as last reported by the master
- `slave_get_connected_devices(device_id)` — All slaves known to the master, with IPs

**Microphone**

- `slave_mute_mic(device_id)` — Mute the microphone
- `slave_unmute_mic(device_id)` — Unmute the microphone
- `slave_toggle_mic(device_id)` — Toggle microphone state
- `slave_restart_audio(device_id)` — Restart the audio engine (stop + start)

**Volume & output**

- `slave_get_volume(device_id)` — Current master volume (0.0–1.0)
- `slave_set_volume(device_id, level)` — Set master volume
- `slave_increase_volume(device_id, amount=0.05)` — Increase volume
- `slave_decrease_volume(device_id, amount=0.05)` — Decrease volume
- `slave_mute_output(device_id)` — Mute output
- `slave_unmute_output(device_id)` — Unmute output

**Brightness**

- `slave_get_brightness(device_id)` — Current display brightness (0–100)
- `slave_set_brightness(device_id, level)` — Set brightness
- `slave_increase_brightness(device_id, amount=10)` — Increase brightness
- `slave_decrease_brightness(device_id, amount=10)` — Decrease brightness

**Power**

- `slave_sleep(device_id, delay=0)` — Suspend (delay in seconds, 0–3600)
- `slave_shutdown(device_id, delay=0)` — Power off
- `slave_restart_system(device_id, delay=0)` — Reboot the OS
- `slave_cancel_shutdown(device_id)` — Cancel a pending shutdown/restart

## Master-Derived Tools

`slave_get_ip_address` and `slave_get_connected_devices` route through the
slave's **authenticated pass-through** endpoints
(`GET /mcp/v1/master/slaves`, `GET /mcp/v1/master/slaves/{id}/ip`). The slave
calls the master with its own `X-Device-Id` / `Bearer` credentials, so this
works on LAN deployments where the MCP host and the slave host differ.

## Integration with Javis

Add to `mcp_servers.json`:

```json
{
  "servers": {
    "javis-slave": {
      "command": "python",
      "args": ["-m", "javis_slave_mcp"],
      "env": {
        "JAVIS_SLAVE_DEVICES": "device1=192.168.1.100:8766"
      },
      "transport": "stdio",
      "approval": "allow"
    }
  }
}
```

Now Javis can use tools like `javis_slave__slave_mute_mic` to control slave devices.

## Implementation Details

The slave app runs an HTTP server on port 8766 alongside the GUI and audio engine. This MCP server connects to slave instances via their HTTP APIs and exposes control tools.

See:
- [Slave HTTP Server](../javis-slave/src/javis_slave/http_server.py) — Endpoints and models
- [Slave App Integration](../javis-slave/src/javis_slave/app.py) — HTTP server lifecycle