MCP per assistenti IA

Il server MCP (Model Context Protocol) di HAM collega un assistente IA ai Suoi dispositivi. L’assistente può vedere l’elenco dei dispositivi, le misurazioni attuali e lo storico. Ogni chiamata viene eseguita con il Suo account e i Suoi permessi su ogni dispositivo.

Dettagli di connessione

Elemento	Valore
Indirizzo	`https://api.hamsystems.eu/mcp/index.php`
Trasporto	HTTP, JSON-RPC 2.0
Versione del protocollo	`2024-11-05`
Autenticazione	Header `Authorization: Bearer-API YOUR_API_KEY`

Crea la chiave API nella pagina Account. Veda l’API REST.

Configurare l’assistente

Crei una chiave API.

Aggiunga il server alla configurazione MCP del Suo assistente. Per Claude Code, il file è .mcp.json:

{
  "mcpServers": {
    "ham": {
      "type": "http",
      "url": "https://api.hamsystems.eu/mcp/index.php",
      "headers": {
        "Authorization": "Bearer-API YOUR_API_KEY"
      }
    }
  }
}

Riavvii l’assistente.
Chieda, per esempio, “Mostrami i miei dispositivi”. L’assistente chiama lo strumento list_devices.

Strumenti

Strumento	Parametri	Risultato
`list_devices`	`compact` (predefinito `true`)	I Suoi dispositivi. Con `compact: true`: `serialno`, `name`, `icon`, `groups`, `floorplans` e `count`. Con `compact: false`: tutti i dettagli, con le impostazioni.
`get_device_state`	`serialno` (un numero o un elenco)	Lo stato attuale. Lo stesso formato di `get_device_state.php`. Veda l’API REST.
`get_device_history`	`serialno`, `level`, `bin`	Le righe dello storico. Gli stessi livelli e bin di scaricare i dati storici.
`get_definitions`	`family_id` (facoltativo), `include_readings` (predefinito `true`)	Le definizioni delle famiglie: misurazioni, uscite, impostazioni
`get_docs`	nessuno	Istruzioni per gli strumenti
`send_command`	`serialno`, `command`	Invia un comando a un dispositivo o a un gruppo. L’assistente ottiene i comandi da `get_docs`.

Un ordine tipico di chiamate: list_devices, poi get_definitions per la famiglia, poi get_device_state o get_device_history.

Prova con curl

curl -X POST https://api.hamsystems.eu/mcp/index.php \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_devices","arguments":{}}}'

Il risultato è in result.content[0].text, come testo JSON:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{\"devices\":[{\"serialno\":\"e11:123\",\"name\":\"Fridge 1\",\"icon\":\"\",\"groups\":[],\"floorplans\":[]}],\"count\":1}" }
    ]
  }
}

Metodi supportati: initialize, notifications/initialized, tools/list, tools/call.

Errori

Codice	Significato
`-32000`	Errore di autenticazione (HTTP 401) o errore dello strumento
`-32700`	Il corpo non è JSON valido
`-32600`	Richiesta JSON-RPC non valida
`-32601`	Metodo sconosciuto
`-32602`	Il nome dello strumento manca
`-32603`	Errore interno

Vedere anche

Chat con l'assistenza