MCP для ИИ-помощников

Сервер HAM MCP (Model Context Protocol) подключает ИИ-помощника к Вашим устройствам. Помощник может видеть список устройств, текущие показания и историю. Каждый вызов выполняется с Вашим аккаунтом и Вашими правами на каждое устройство.

Данные подключения

Пункт	Значение
Адрес	`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`	Строки истории. Те же уровни и bins, что и в загрузке исторических данных.
`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`	Внутренняя ошибка

См. также

Чат с поддержкой