MCP для AI-асистентів

Сервер MCP (Model Context Protocol) HAM підключає AI-асистента до ваших пристроїв. Асистент бачить список пристроїв, поточні показники та історію. Кожен виклик виконується з вашим обліковим записом і вашими дозволами на кожен пристрій.

Дані підключення

Пункт	Значення
Адреса	`https://api.hamsystems.eu/mcp/index.php`
Транспорт	HTTP, JSON-RPC 2.0
Версія протоколу	`2024-11-05`
Автентифікація	Заголовок `Authorization: Bearer-API YOUR_API_KEY`

Ви створюєте API ключ на сторінці Обліковий запис. Див. REST API.

Налаштуйте асистента

Створіть API ключ.

Додайте сервер до конфігурації MCP вашого асистента. Для Claude Code файл називається .mcp.json:

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

Перезапустіть асистента.
Запитайте, наприклад, “Покажи мої пристрої”. Асистент викликає інструмент list_devices.

Інструменти

Інструмент	Параметри	Результат
`list_devices`	`compact` (за замовчуванням `true`)	Ваші пристрої. З `compact: true`: `serialno`, `name`, `icon`, `groups`, `floorplans` і `count`. З `compact: false`: усі дані, з налаштуваннями.
`get_device_state`	`serialno` (один номер або список)	Поточний стан. Той самий формат, що й у `get_device_state.php`. Див. REST API.
`get_device_history`	`serialno`, `level`, `bin`	Рядки історії. Ті самі рівні і bin, що в завантаженні історичних даних.
`get_definitions`	`family_id` (необов’язково), `include_readings` (за замовчуванням `true`)	Визначення сімейств: показники, виходи, налаштування
`get_docs`	немає	Інструкції для інструментів
`send_command`	`serialno`, `command`	Надсилає команду пристрою або групі. Асистент отримує команди з `get_docs`.

Звичайний порядок викликів: list_devices, потім get_definitions для сімейства, потім get_device_state або get_device_history.

Перевірка з 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":{}}}'

Результат є в result.content[0].text як текст JSON:

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

Підтримувані методи: initialize, notifications/initialized, tools/list, tools/call.

Помилки

Код	Що це означає
`-32000`	Помилка автентифікації (HTTP 401) або помилка інструмента
`-32700`	Тіло не є правильним JSON
`-32600`	Неправильний запит JSON-RPC
`-32601`	Невідомий метод
`-32602`	Назва інструмента відсутня
`-32603`	Внутрішня помилка

Див. також

Чат із підтримкою