Servidor MCP — Acesso de IA para o OpenSprinkler

A integração do protocolo MCP (Model Context Protocol) do OpenSprinkler permite que assistentes virtuais baseados em inteligência artificial (IA) consultem e controlem o OpenSprinkler por meio de ferramentas estruturadas.

Páginas detalhadas de suporte:

Modos de Operação

Servidor MCP Integrado no Firmware

O servidor MCP integrado é executado diretamente em builds de firmware ESP32 com USE_OTF ativado:

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

A autenticação utiliza o mesmo hash MD5 da senha do administrador da REST API: ?pw=, o cabeçalho X-OS-Password ou Bearer Token.

Plataforma: apenas ESP32 / ESP32-C5 com USE_OTF; não disponível para ESP8266 e OSPi.

Servidor MCP Externo Node.js

O servidor externo em tools/mcp-server/ é executado externamente ao firmware e expõe a REST API por meio de stdio. Ele funciona com controladores ESP8266, ESP32 e OSPi, oferecendo um conjunto maior de ferramentas, incluindo sensores, monitores, Zigbee, BLE e recursos do sistema, desde que o controlador de destino forneça suporte para essas funções.

Configuração

Pré-requisitos

Node.js 18 ou superior.
Um controlador OpenSprinkler acessível.
A senha do administrador como hash MD5.

Instalação e Build

cd tools/mcp-server
npm install
npm run build

VS Code / GitHub Copilot

Adicione ao seu arquivo .vscode/mcp.json:

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

Claude Desktop

Adicione ao seu arquivo ~/.config/claude/claude_desktop_config.json:

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

Calcular o Hash da Senha

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

Visão Geral das Ferramentas

Categoria	Exemplo de Ferramentas
Status do Controlador	`get_all`, `get_controller_variables`, `get_options`, `get_debug`, `get_system_resources`
Estações e Programas	`get_stations`, `get_station_status`, `get_programs`, `manual_station_run`, `manual_program_start`, `change_program`
Sensores e Logs	`get_sensors`, `get_sensor_values`, `get_sensor_log`, `get_sensor_types`, `backup_sensor_config`
Rede Sem Fio OpenSprinklerPro	`get_ieee802154_config`, `get_zigbee_devices`, `get_zigbee_status`, `get_ble_devices`, `get_rainmaker_status`
Automação	`list_adjustments`, `configure_adjustment`, `list_monitors`, `configure_monitor`

Diagnóstico do Sistema

O servidor MCP não possui diálogo de interface próprio. Para diagnósticos no local, a tela de Diagnóstico do Sistema ajuda a verificar a versão do firmware, recursos de memória e integrações.

Diagnóstico do Sistema