Server MCP — accesso IA per OpenSprinkler

L’integrazione MCP (Model Context Protocol) consente agli assistenti IA di interrogare e controllare un controller OpenSprinkler tramite strumenti documentati.

Questa pagina copre solo configurazione MCP e modalità operative. Gli altri temi sono separati:

Modalità operative

MCP integrato nel firmware

Il server MCP integrato funziona direttamente nei firmware ESP32 con USE_OTF:

POST http://<controller-ip>/mcp
Content-Type: application/json

L’autenticazione usa lo stesso hash della password amministratore dell’API REST: ?pw=, header X-OS-Password o bearer token.

Disponibilità: solo ESP32 / ESP32-C5 con USE_OTF; non ESP8266 e non OSPi.

Server MCP Node.js esterno

Il server esterno in tools/mcp-server/ gira fuori dal firmware e pubblica l’API REST via stdio. Funziona con ESP8266, ESP32 e OSPi, con strumenti per sensori, monitor, Zigbee, BLE e risorse sistema quando supportati dal controller.

Configurazione

cd tools/mcp-server
npm install
npm run build

Esempio VS Code / GitHub Copilot:

{
  "servers": {
    "opensprinkler": {
      "type": "stdio",
      "command": "node",
      "args": ["tools/mcp-server/dist/index.js"],
      "env": {
        "OS_BASE_URL": "http://<CONTROLLER-IP>",
        "OS_PASSWORD_HASH": "<MD5-HASH>"
      }
    }
  }
}

Calcolo hash:

echo -n "password_admin" | md5sum | awk '{print $1}'

Panoramica strumenti

Area	Esempi di strumenti
Stato controller	`get_all`, `get_controller_variables`, `get_options`, `get_debug`, `get_system_resources`
Stazioni e programmi	`get_stations`, `get_station_status`, `get_programs`, `manual_station_run`, `change_program`
Sensori e log	`get_sensors`, `get_sensor_values`, `get_sensor_log`, `backup_sensor_config`
Radio OpenSprinklerPro	`get_ieee802154_config`, `get_zigbee_devices`, `get_zigbee_status`, `get_ble_devices`, `get_rainmaker_status`
Automazione	`list_adjustments`, `configure_adjustment`, `list_monitors`, `configure_monitor`

Il server MCP non ha una schermata UI propria. Per la diagnostica locale usare Diagnostica di sistema.

Diagnostica di sistema