MCP dla asystentów AI

Serwer HAM MCP (Model Context Protocol) łączy asystenta AI z Twoimi urządzeniami. Asystent może zobaczyć listę urządzeń, bieżące odczyty i historię. Każde wywołanie działa z Twoim kontem i Twoimi uprawnieniami do każdego urządzenia.

Dane połączenia

Element	Wartość
Adres	`https://api.hamsystems.eu/mcp/index.php`
Transport	HTTP, JSON-RPC 2.0
Wersja protokołu	`2024-11-05`
Uwierzytelnianie	Nagłówek `Authorization: Bearer-API YOUR_API_KEY`

Klucz API tworzysz na stronie Konto. Zobacz REST API.

Konfiguracja asystenta

Utwórz klucz API.

Dodaj serwer do konfiguracji MCP swojego asystenta. Dla Claude Code plik to .mcp.json:

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

Zrestartuj asystenta.
Zapytaj na przykład “Pokaż moje urządzenia”. Asystent wywołuje narzędzie list_devices.

Narzędzia

Narzędzie	Parametry	Wynik
`list_devices`	`compact` (domyślnie `true`)	Twoje urządzenia. Z `compact: true`: `serialno`, `name`, `icon`, `groups`, `floorplans` i `count`. Z `compact: false`: wszystkie szczegóły, z ustawieniami.
`get_device_state`	`serialno` (jeden numer lub lista)	Bieżący stan. Ten sam format co `get_device_state.php`. Zobacz REST API.
`get_device_history`	`serialno`, `level`, `bin`	Wiersze historii. Te same poziomy i biny co w pobieraniu danych historycznych.
`get_definitions`	`family_id` (opcjonalny), `include_readings` (domyślnie `true`)	Definicje rodzin: odczyty, wyjścia, ustawienia
`get_docs`	brak	Instrukcje dla narzędzi
`send_command`	`serialno`, `command`	Wysyła polecenie do urządzenia lub grupy. Asystent bierze polecenia z `get_docs`.

Typowa kolejność wywołań: list_devices, potem get_definitions dla rodziny, potem get_device_state lub get_device_history.

Test za pomocą 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":{}}}'

Wynik jest w result.content[0].text, jako tekst JSON:

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

Obsługiwane metody: initialize, notifications/initialized, tools/list, tools/call.

Błędy

Kod	Znaczenie
`-32000`	Błąd uwierzytelniania (HTTP 401) lub błąd narzędzia
`-32700`	Treść nie jest poprawnym JSON
`-32600`	Niepoprawne żądanie JSON-RPC
`-32601`	Nieznana metoda
`-32602`	Brakuje nazwy narzędzia
`-32603`	Błąd wewnętrzny

Zobacz też

Czat z pomocą techniczną