javis/javis-slave-mcp/README.md

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); 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

# 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):

{
  "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

pip install -e .

Usage

Run the server:

python -m javis_slave_mcp

Or with a custom config:

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:

{
  "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 — Endpoints and models
• Slave App Integration — HTTP server lifecycle