v1.0

javis-slave-mcp/README.md

@@ -18,23 +18,41 @@ endpoints are identical on both.
 
 ## 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
+# 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`:
+Create `~/.javis/slave_mcp_config.json` (or point `JAVIS_SLAVE_MCP_CONFIG` at it):
 
 ```json
 {
   "slaves": {
     "bedroom": {
       "host": "192.168.1.100",
-      "port": 8766
+      "port": 8766,
+      "token": "<output of javis-slave --show-control-token>"
     },
     "kitchen": {
       "host": "192.168.1.101",
@@ -44,6 +62,8 @@ Create `~/.javis/slave_mcp_config.json`:
 }
 ```
 
+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).
@@ -72,6 +92,10 @@ 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**
 
@@ -101,14 +125,14 @@ All tools take `device_id` (default `"localhost"`) unless noted otherwise.
 
 - `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
+- `slave_increase_brightness(device_id, amount=5)` — Increase brightness
+- `slave_decrease_brightness(device_id, amount=5)` — 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_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
@@ -118,6 +142,9 @@ 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
 
@@ -130,7 +157,8 @@ Add to `mcp_servers.json`:
       "command": "python",
       "args": ["-m", "javis_slave_mcp"],
       "env": {
-        "JAVIS_SLAVE_DEVICES": "device1=192.168.1.100:8766"
+        "JAVIS_SLAVE_DEVICES": "device1=192.168.1.100:8766",
+        "JAVIS_SLAVE_TOKEN": "<slave control token>"
       },
       "transport": "stdio",
       "approval": "allow"