MCP għall-assistenti AI

Is-server MCP (Model Context Protocol) ta’ HAM jikkonnettja assistent AI mal-apparati tagħkom. L-assistent jista’ jara l-lista tal-apparati, il-qari attwali u l-istorja. Kull sejħa taħdem bil-kont tagħkom u bil-permessi tagħkom fuq kull apparat.

Id-dettalji tal-konnessjoni

Oġġett	Valur
Indirizz	https://api.hamsystems.eu/mcp/index.php
Trasport	HTTP, JSON-RPC 2.0
Verżjoni tal-protokoll	2024-11-05
Awtentikazzjoni	Header Authorization: Bearer-API YOUR_API_KEY

Toħolqu ċ-ċavetta API fil-paġna Kont. Araw ir-REST API.

Issettjaw l-assistent

1. Oħolqu ċavetta API.

2. Żidu s-server mal-konfigurazzjoni MCP tal-assistent tagħkom. Għal Claude Code, il-fajl huwa .mcp.json:

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

3. Erġgħu ibdew l-assistent.

4. Staqsu, pereżempju, “Urini l-apparati tiegħi”. L-assistent isejjaħ l-għodda list_devices.

Attenzjoni

L-assistent għandu l-istess aċċess bħalkom. Jista’ jikkontrolla l-outputs fuq l-apparati fejn għandkom permess tal-kitba. Taqsmux il-fajl tal-konfigurazzjoni, għax fih iċ-ċavetta tagħkom.

Għodod

Għodda	Parametri	Riżultat
list_devices	compact (default true)	L-apparati tagħkom. B’compact: true: serialno, name, icon, groups, floorplans u count. B’compact: false: id-dettalji kollha, bis-settings.
get_device_state	serialno (numru wieħed jew lista)	L-istat attwali. L-istess format ta’ get_device_state.php. Araw ir-REST API.
get_device_history	serialno, level, bin	Ir-ringieli tal-istorja. L-istess livelli u bins bħal f’niżżlu data storika.
get_definitions	family_id (fakultattiv), include_readings (default true)	Id-definizzjonijiet tal-familji: qari, outputs, settings
get_docs	xejn	Istruzzjonijiet għall-għodod
send_command	serialno, command	Jibgħat kmand lil apparat jew lil grupp. L-assistent jieħu l-kmandi minn get_docs.

Ordni tipika tas-sejħiet: list_devices, imbagħad get_definitions għall-familja, imbagħad get_device_state jew get_device_history.

Ittestjaw b’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":{}}}'

Ir-riżultat jinsab f’result.content[0].text, bħala test JSON:

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

Il-metodi appoġġjati: initialize, notifications/initialized, tools/list, tools/call.

Żbalji

Kodiċi	Tifsira
-32000	Żball tal-awtentikazzjoni (HTTP 401) jew żball tal-għodda
-32700	Il-body mhuwiex JSON validu
-32600	Talba JSON-RPC mhux valida
-32601	Metodu mhux magħruf
-32602	L-isem tal-għodda huwa nieqes
-32603	Żball intern

Araw ukoll

• REST API
• Sigurtà