# StarLine MCP

MCP-сервер для управления автосигнализацией **StarLine** через ИИ-агента (Claude и др.).

Агент вызывает понятные инструменты (`list_devices`, `get_status`, `set_engine`…), а сервер
прячет всю «грязь»: 4-шаговую авторизацию StarLineID, кэш токенов и маппинг команд в облачный API.

```
AI-агент (Claude) ──tools──► StarLine MCP ──REST──► облако StarLine ──GSM──► блок в машине
```

## Архитектура

| Слой | Файл | Ответственность |
|------|------|-----------------|
| Конфиг | `config.py` | учётные данные из `.env` |
| Авторизация | `auth.py` | getCode → getToken → user/login → auth.slid, кэш `slnet` (24ч) |
| Клиент API | `client.py` | список/статус устройств, отправка команд, авто-переавторизация |
| MCP-сервер | `server.py` | инструменты для агента |

## Безопасность

Инструменты разделены на два класса:

- **read-only** (`list_devices`, `get_status`, `get_location`) — выполняются свободно.
- **команды управления** (`set_security`, `set_engine`, `set_heater`, `set_channel`) —
  отказывают без `confirm=true`. Агент **не должен** подставлять `confirm` сам — подтверждение
  исходит от человека. Рекомендуется дополнительно требовать approval на эти инструменты
  в настройках хоста (Claude Desktop / Claude Code permissions).

> ⚠️ Запуск двигателя и снятие с охраны — физические действия с реальной машиной.
> Относитесь к ним как к необратимым.

## Установка

Изолированный venv обязателен: на машине бывает несколько Python, а голый `python`
в конфиге MCP-хоста резолвится непредсказуемо (главная причина «не запускается»).

```bash
cd "C:/GIT/StarLine MCP"
py -3.12 -m venv .venv
.venv/Scripts/python.exe -m pip install -e .   # ставит пакет + зависимости в venv
cp .env.example .env                            # затем заполнить
```

После `-e .` пакет импортируется из venv — `PYTHONPATH` задавать **не нужно**.

Самодиагностика (проверяет импорты и конфиг, печатает в stderr):

```bash
.venv/Scripts/python.exe -m starline_mcp.server --healthcheck
```

`.env`:

```
STARLINE_APP_ID=...         # из https://my.starline.ru/developer
STARLINE_APP_SECRET=...
STARLINE_LOGIN=...          # аккаунт my.starline.ru
STARLINE_PASSWORD=...
```

## Проверка доступа

```bash
.venv/Scripts/python.exe -m starline_mcp.check_auth
```

Залогинится и выведет список ваших устройств со статусом. Это лучший первый шаг —
убедиться, что API-доступ реально работает, до подключения к агенту.

## Запуск MCP-сервера

```bash
.venv/Scripts/python.exe -m starline_mcp.server
```

Подключение к Claude Code: в корне уже лежит `.mcp.json` с **абсолютным путём к venv**
(не голый `python` — это принципиально):

```json
{
  "mcpServers": {
    "starline": {
      "command": "C:/GIT/StarLine MCP/.venv/Scripts/python.exe",
      "args": ["-m", "starline_mcp.server"],
      "cwd": "C:/GIT/StarLine MCP",
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}
```

> Если хост (Hermes/Claude Code) «не видит модуль» — почти всегда это голый `python`
> в команде вместо абсолютного пути к `.venv/Scripts/python.exe`. Не подмешивай `PYTHONPATH`
> и не плоди wrapper-скрипты — после `pip install -e .` это не нужно.

## Подключение к Claude Code

В корне лежит `.mcp.json` — Claude Code подхватит сервер автоматически при запуске в этой папке.
Список инструментов появится после подтверждения подключения MCP-сервера.

> Рекомендация: в настройках прав потребуй approval на инструменты `set_*` (команды управления),
> чтобы каждое физическое действие с машиной подтверждалось вручную.

## Статус

- [x] Авторизация (4 шага) + кэш токенов
- [x] Чтение: список устройств, статус, GPS, баланс SIM
- [x] Команды с подтверждением: охрана, двигатель, подогреватель, доп. канал, поиск авто
- [x] Проверено на живом аккаунте
- [x] Авто-выбор команды под модель блока (`ign` vs `ign_start`/`ign_stop`)
- [x] Проверка поддержки команды конкретным блоком (по `controls`)
- [x] Кэш списка устройств (TTL 15с)
- [x] Конфиг `.mcp.json` для Claude Code
- [ ] Боевая проверка отправки команд (требует согласия владельца — физическое действие)
- [ ] Обработка 2FA в интерактиве (если включится на аккаунте)

## Источники

Эндпоинты и алгоритмы сверены по:
- <https://github.com/Anonym-tsk/starline> (pip-пакет `starline`)
- `homeassistant/components/starline`
- <https://developer.starline.ru/>