179 lines
6.0 KiB
Markdown
179 lines
6.0 KiB
Markdown
# 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
|
||
|
||
### Authentication
|
||
|
||
The slave's control API requires authentication (it can shut the machine down):
|
||
|
||
- **Same machine** (`127.0.0.1` / `::1`): nothing to configure — this server
|
||
always sends the `X-Javis-Control: 1` header, which the slave accepts from
|
||
loopback callers only.
|
||
- **Other machines**: send the slave's control token as `Authorization: Bearer …`.
|
||
Print it on the slave with `javis-slave --show-control-token` (or open
|
||
*Einstellungen* in the slave GUI), then set it here via `JAVIS_SLAVE_TOKEN`
|
||
(default for all devices), `id=TOKEN@host:port` in `JAVIS_SLAVE_DEVICES`,
|
||
or `"token"` in the config file.
|
||
|
||
### Environment Variables
|
||
|
||
```bash
|
||
# Comma-separated list of device_id=host:port (or device_id=TOKEN@host:port)
|
||
export JAVIS_SLAVE_DEVICES="device1=192.168.1.100:8766,device2=192.168.1.101:8766"
|
||
# Default control token for devices without their own
|
||
export JAVIS_SLAVE_TOKEN="…"
|
||
```
|
||
|
||
A malformed entry is skipped with a warning; the remaining entries still load.
|
||
|
||
### Config File
|
||
|
||
Create `~/.javis/slave_mcp_config.json` (or point `JAVIS_SLAVE_MCP_CONFIG` at it):
|
||
|
||
```json
|
||
{
|
||
"slaves": {
|
||
"bedroom": {
|
||
"host": "192.168.1.100",
|
||
"port": 8766,
|
||
"token": "<output of javis-slave --show-control-token>"
|
||
},
|
||
"kitchen": {
|
||
"host": "192.168.1.101",
|
||
"port": 8766
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
The file contains secrets — keep it readable only by your user.
|
||
|
||
### 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.
|
||
Failures (unknown device, slave unreachable, 401, …) are returned as MCP tool
|
||
errors (`isError: true`). Every tool carries MCP annotations
|
||
(`readOnlyHint` / `destructiveHint` / `idempotentHint`); the power tools are
|
||
marked destructive so clients can ask for confirmation.
|
||
|
||
**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=5)` — Increase brightness
|
||
- `slave_decrease_brightness(device_id, amount=5)` — Decrease brightness
|
||
|
||
**Power**
|
||
|
||
- `slave_sleep(device_id)` — Suspend
|
||
- `slave_shutdown(device_id, delay=0)` — Power off (delay in seconds, 0–3600)
|
||
- `slave_restart_system(device_id, delay=0)` — Reboot the OS (delay 0–3600)
|
||
- `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.
|
||
`slave_get_ip_address` first reads the slave's real `device_id` from its
|
||
`/mcp/v1/status`, so it also works when you address the slave by an alias
|
||
such as `localhost`.
|
||
|
||
## 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",
|
||
"JAVIS_SLAVE_TOKEN": "<slave control token>"
|
||
},
|
||
"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
|