MCP para assistentes de IA

O servidor MCP (Model Context Protocol) da HAM liga um assistente de IA aos seus dispositivos. O assistente pode ver a lista de dispositivos, as leituras atuais e o histórico. Cada chamada corre com a sua conta e com as suas permissões em cada dispositivo.

Dados da ligação

Item	Valor
Endereço	`https://api.hamsystems.eu/mcp/index.php`
Transporte	HTTP, JSON-RPC 2.0
Versão do protocolo	`2024-11-05`
Autenticação	Cabeçalho `Authorization: Bearer-API YOUR_API_KEY`

Cria a chave API na página Conta. Consulte a API REST.

Configurar o assistente

Crie uma chave API.

Adicione o servidor à configuração MCP do seu assistente. Para o Claude Code, o ficheiro é .mcp.json:

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

Reinicie o assistente.
Pergunte, por exemplo, “Mostra-me os meus dispositivos”. O assistente chama a ferramenta list_devices.

Ferramentas

Ferramenta	Parâmetros	Resultado
`list_devices`	`compact` (predefinição `true`)	Os seus dispositivos. Com `compact: true`: `serialno`, `name`, `icon`, `groups`, `floorplans` e `count`. Com `compact: false`: todos os detalhes, com as definições.
`get_device_state`	`serialno` (um número ou uma lista)	O estado atual. O mesmo formato de `get_device_state.php`. Consulte a API REST.
`get_device_history`	`serialno`, `level`, `bin`	As linhas do histórico. Os mesmos níveis e bins de transferir dados históricos.
`get_definitions`	`family_id` (opcional), `include_readings` (predefinição `true`)	As definições da família: leituras, saídas, definições
`get_docs`	nenhum	Instruções para as ferramentas
`send_command`	`serialno`, `command`	Envia um comando para um dispositivo ou um grupo. O assistente obtém os comandos com `get_docs`.

Uma ordem de chamadas típica: list_devices, depois get_definitions para a família e depois get_device_state ou get_device_history.

Teste com 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":{}}}'

O resultado está em result.content[0].text, como texto JSON:

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

Métodos suportados: initialize, notifications/initialized, tools/list, tools/call.

Erros

Código	Significado
`-32000`	Erro de autenticação (HTTP 401) ou erro da ferramenta
`-32700`	O corpo não é JSON válido
`-32600`	Pedido JSON-RPC inválido
`-32601`	Método desconhecido
`-32602`	Falta o nome da ferramenta
`-32603`	Erro interno

Consulte também

Chat com o suporte