Metadata-Version: 2.4
Name: redbees-modem-mcp
Version: 0.2.1
Summary: MCP server for the Redbees modem (Zephyr RTOS): generation and verification of Lua scripts, device access over SMP (mcumgr), and flashing via esptool.
Project-URL: Homepage, https://github.com/dmkuzmin/rb-modem-assistant
Project-URL: Repository, https://github.com/dmkuzmin/rb-modem-assistant
Author-email: dmkuzmin <kuzmin.d@redbees.ru>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: esp32,esptool,lua,mcp,mcumgr,modem,redbees,smp,zephyr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Requires-Dist: bleak>=3.0.0
Requires-Dist: esptool>=5.3.0
Requires-Dist: huggingface-hub>=1.4.0
Requires-Dist: intelhex>=2.3.0
Requires-Dist: langchain-community>=0.4.0
Requires-Dist: langchain-huggingface>=1.2.0
Requires-Dist: langchain-text-splitters>=1.1.0
Requires-Dist: lupa>=2.8
Requires-Dist: mcp[cli]>=1.28.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pyserial>=3.5
Requires-Dist: sentence-transformers>=5.0.0
Requires-Dist: smp>=4.1.0
Requires-Dist: smpclient<8,>=7.2.0
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: torch>=2.2
Provides-Extra: semantic
Description-Content-Type: text/markdown

# redbees-modem-mcp

MCP-сервер для модема **Redbees** (Zephyr RTOS): пошаговая генерация и проверка
Lua-скриптов, полный доступ к устройству по **SMP** (mcumgr) через
serial/BLE/UDP и прошивка через **esptool**. Подключается к любому MCP-хосту
(Claude Desktop, IDE, Codex и т.д.). Работает офлайн.

> 🚀 **Новичку** — начните с раздела [«Быстрый старт с нуля»](#быстрый-старт-с-нуля)
> ниже: установка на чистой Windows/Linux (VS Code + Cline), простым языком, по
> шагам. Всё, что после него, — технический справочник.

## Быстрый старт с нуля

Это раздел для тех, кто начинает **с чистой системы** — ничего заранее
устанавливать не нужно. К концу у вас будет: редактор **VS Code** с ИИ-ассистентом
**Cline**, подключённый к нему **MCP-сервер** `redbees-modem-mcp` (генерация Lua,
доступ к модему, прошивка) и выбранная **модель ИИ**. Займёт ~20–30 минут (в
основном ожидание загрузок).

1. [Что понадобится](#что-понадобится)
2. [Шаг 1. Установить VS Code](#шаг-1-установить-vs-code)
3. [Шаг 2. Установить расширение Cline](#шаг-2-установить-расширение-cline)
4. [Шаг 3. Установить uv](#шаг-3-установить-uv)
5. [Шаг 4. Скачать MCP-сервер](#шаг-4-скачать-mcp-сервер)
6. [Шаг 5. Скачать поисковую модель](#шаг-5-скачать-поисковую-модель)
7. [Шаг 6. Прописать MCP-сервер в Cline](#шаг-6-прописать-mcp-сервер-в-cline)
8. [Шаг 7. Подключить модель ИИ (LLM) в Cline](#шаг-7-подключить-модель-ии-llm-в-cline)
9. [Шаг 8. Проверка](#шаг-8-проверка)

### Что понадобится

- Компьютер с **Windows 10/11** или **Linux** и доступом в интернет.
- **Модем Redbees** и USB-кабель — понадобится для команд к устройству (генерацию
  Lua можно пробовать и без модема).
- **Доступ к модели ИИ.** Cline сам ИИ не содержит — он обращается к провайдеру.
  Варианты:
  - **Anthropic (Claude)** — ключ на <https://console.anthropic.com> → *API Keys*;
  - **OpenRouter** (<https://openrouter.ai>) — один ключ на много моделей;
  - **Ollama с облачной моделью** — большие модели считаются в облаке Ollama, своя
    мощная видеокарта не нужна (см. вариант в [шаге 7](#шаг-7-подключить-модель-ии-llm-в-cline)).

> Две разные «модели» не перепутайте:
> - **модель ИИ (LLM)** — «мозг» ассистента, подключается ключом в Cline (шаг 7);
> - **поисковая модель (эмбеддинги)** — нужна серверу для поиска по базе знаний,
>   скачивается в [шаге 5](#шаг-5-скачать-поисковую-модель). Её настраивать не надо.

### Шаг 1. Установить VS Code

**Windows:**
1. Откройте <https://code.visualstudio.com> и нажмите **Download for Windows**.
2. Запустите скачанный установщик, жмите **Далее** со значениями по умолчанию.

**Linux:**
```bash
# Ubuntu / Debian — через snap (проще всего):
sudo snap install code --classic
```
Если `snap` нет — скачайте `.deb` с <https://code.visualstudio.com> и установите
двойным кликом или `sudo apt install ./code_*.deb`.

Запустите VS Code.

### Шаг 2. Установить расширение Cline

1. В VS Code слева нажмите значок **Extensions** (или `Ctrl+Shift+X`).
2. В поиске введите **Cline**.
3. У расширения **Cline** нажмите **Install**.
4. Слева появится новый значок Cline — на него будем нажимать дальше.

### Шаг 3. Установить uv

`uv` — маленькая программа, которая **сама развернёт окружение** сервера и запустит
его одной командой. Свой Python ставить не нужно.

Откройте терминал (**Windows:** меню Пуск → «PowerShell»; **Linux:** «Terminal»).

**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

После установки **закройте и снова откройте терминал**, затем проверьте:
```
uvx --version
```
Должна появиться строка с версией. Если «команда не найдена» — см.
[«Устранение проблем»](#устранение-проблем).

### Шаг 4. Скачать MCP-сервер

Установите сам сервер заранее — иначе при первом подключении Cline может не
дождаться его загрузки (~2 ГБ на диске, в основном PyTorch) и отключиться по
таймауту.

В терминале:
```
uv tool install redbees-modem-mcp
```
Дождитесь строк вида:
```
Installed redbees-modem-mcp
Installed 2 executables: redbees-modem-mcp, redbees-modem-mcp-download-model
```
Первый раз — несколько минут, зависит от скорости интернета. Повторные
переустановки ничего заново не качают — всё берётся из кэша uv.

> Понадобится **~2 ГБ свободного места** на системном диске. Если места мало,
> загрузка оборвётся с ошибкой «Недостаточно места на диске» (os error 112).

### Шаг 5. Скачать поисковую модель

Модель для семантического поиска по базе знаний (~1 ГБ) тоже стоит скачать
заранее, а не ждать первого запроса в Cline.

В том же терминале команда из шага 4 уже добавила нужную команду — просто
запустите:
```
redbees-modem-mcp-download-model
```
Дождитесь строки `Done! Model saved to: ...` (первый раз — несколько минут).
Модель сохранится в кэш (`~/.cache/redbees-modem-mcp`) и повторно скачиваться
не будет.

### Шаг 6. Прописать MCP-сервер в Cline

1. В VS Code нажмите значок **Cline** слева.
2. В окне Cline нажмите значок **MCP Servers** (вверху), затем **Configure MCP
   Servers** — откроется файл `cline_mcp_settings.json`.
3. Вставьте в него это (если в файле уже есть `{ }` — впишите блок `redbees-modem`
   внутрь `mcpServers`) и **сохраните** (`Ctrl+S`):

```json
{
  "mcpServers": {
    "redbees-modem": {
      "command": "redbees-modem-mcp",
      "args": [],
      "env": {},
      "disabled": false,
      "autoApprove": [],
      "timeout": 3600
    }
  }
}
```

Команда `redbees-modem-mcp` — тот же исполняемый файл, который установил
[шаг 4](#шаг-4-скачать-mcp-сервер) (`uv tool install`); используем его напрямую,
а не через `uvx`, чтобы не ставить те же ~2 ГБ зависимостей второй раз в
отдельную временную среду.

После сохранения Cline сам запустит сервер. В списке MCP напротив `redbees-modem`
должен загореться **зелёный** индикатор. Первый запуск может занять до минуты
(модель грузится в память).

> Если Cline пишет **«redbees-modem-mcp not found»** — см.
> [«Устранение проблем»](#устранение-проблем).

### Шаг 7. Подключить модель ИИ (LLM) в Cline

1. В окне Cline нажмите значок **шестерёнки** (Settings).
2. В **API Provider** выберите провайдера (например, **Anthropic**).
3. Вставьте свой **API-ключ** (из раздела [«Что понадобится»](#что-понадобится)).
4. Выберите **модель** (например, свежую модель Claude) и сохраните.

Теперь у ассистента есть «мозг». Проверять — на следующем шаге.

**Вариант: Ollama с облачной моделью.** Если не хотите платный API-ключ
Anthropic/OpenAI, можно подключить **Ollama** и запускать большие модели **в
облаке Ollama** — тяжёлую модель считают серверы Ollama, локальная видеокарта
не нужна, а Cline обращается к локальному Ollama как обычно.

1. Установите Ollama с <https://ollama.com/download> (Windows/Linux/macOS).
2. Войдите в аккаунт Ollama (нужно для облачных моделей) — в терминале:
   ```
   ollama signin
   ```
   (или просто следуйте подсказке при первом запуске облачной модели).
3. Скачайте облачную модель — у неё суффикс `-cloud`, например:
   ```
   ollama pull gpt-oss:120b-cloud
   ```
   Другие варианты: `qwen3-coder:480b-cloud`, `deepseek-v3.1:671b-cloud`.
4. В настройках Cline выберите **API Provider = Ollama**, оставьте Base URL
   `http://localhost:11434` и выберите скачанную облачную модель.

> Ollama умеет работать и **полностью локально** (маленькая модель на вашем
> компьютере, без входа в аккаунт и без облака) — но для сложной генерации Lua
> облачные модели заметно сильнее.

### Шаг 8. Проверка

1. Подключите модем по USB.
   - **Windows:** он появится как порт `COM3`/`COM5` и т.п. (посмотреть можно в
     «Диспетчере устройств» → «Порты (COM и LPT)»).
   - **Linux:** обычно `/dev/ttyUSB0` или `/dev/ttyACM0`.
2. В окне чата Cline напишите простой запрос, например:
   > Сгенерируй Lua-скрипт, который выводит статус модема.

   или, с подключённым модемом:
   > Запусти диагностику устройства на COM5.
3. Cline вызовет инструменты сервера. При первом вызове может думать чуть дольше.
   Когда инструмент «пишет» в устройство (прошивка, запись настроек), сервер
   сначала покажет **превью** и выполнит действие только после подтверждения —
   это нормально и безопасно.

Готово 🎉 Обновление сервера до новой версии не автоматическое (он установлен
через `uv tool install`): `uv tool upgrade redbees-modem-mcp`, затем
перезапустите сервер в Cline.

---

## Установка (другие способы)

Кроме `uv tool install` из раздела выше, сервер можно поставить и так:

### Через uvx (без установки)

```bash
uvx redbees-modem-mcp
```
`uvx` (часть [uv](https://docs.astral.sh/uv/)) сам скачивает и запускает пакет
эфемерно — отдельный venv не создаётся, но каждый запуск заново резолвит
окружение (из уже скачанного кэша, не по сети).

### Через pip

```bash
pip install redbees-modem-mcp
```

### Из исходников (для разработки)

```bash
pip install -e .        # RAG-зависимости теперь в core (torch и пр. включены)
```

## Запуск

Проще всего — **готовые скрипты-лаунчеры в корне проекта**: поднимают локальный
**HTTP-сервер** (streamable-http) на `http://127.0.0.1:8082/mcp`. Сами находят
Python из venv (`.venv`, затем системный) — отдельный exe не нужен. **Все
переменные сервера — и обязательные, и опциональные — выписаны в блоке НАСТРОЙКИ
в начале каждого скрипта** со значениями по умолчанию: транспорт, порт, профиль
инструментов (`RB_TOOLSET`), модель, токен-бюджет и опциональные переопределения
путей — правь прямо там.

```powershell
.\run_server.ps1          # Windows PowerShell
run_server.bat            # Windows: двойной клик или cmd
```
```bash
./run_server.sh           # Linux/macOS (chmod +x один раз)
```

> stdio-лаунчера нет намеренно: в stdio-режиме сервер поднимает **сам MCP-хост**
> через `mcp_config.json` (см. ниже) — запускать его руками не нужно.

> **Нет файла `redbees-modem-mcp.exe`, только `.py`?** Это нормально. Exe **не
> хранится в репозитории** — это генерируемый **console-script**, который создаёт
> `pip install -e .` в папке `Scripts` твоего venv (а `.venv/` в `.gitignore`).
> Лаунчеры и `python -m` его не требуют.

**Вручную, без лаунчера.** `redbees-modem-mcp` — это console-script; откуда он
вызывается, зависит от способа установки:

- **`uv tool install` / uvx**: команда сама резолвит и запускает пакет.
- **pip / из исходников**: скрипт кладётся в **папку Scripts твоего venv**
  (`\.venv\Scripts\redbees-modem-mcp.exe`). Голое имя `redbees-modem-mcp`
  сработает, **только если этот venv активирован**. Иначе — ошибка «команда не
  распознана».

Надёжные способы (Windows PowerShell, установка из исходников):

```powershell
# 1) активировать venv, потом звать по имени
.\.venv\Scripts\Activate.ps1
redbees-modem-mcp

# 2) без активации — полный путь к exe в venv
.\.venv\Scripts\redbees-modem-mcp.exe

# 3) без активации — через python -m (тот же venv)
.\.venv\Scripts\python.exe -m redbees_modem_mcp

# HTTP-режим без лаунчера (то же, что делает run_server.ps1):
$env:RB_TRANSPORT="streamable-http"; $env:RB_PORT="8082"; .\.venv\Scripts\python.exe -m redbees_modem_mcp
```

### Транспорты

Сервер поддерживает два транспорта (выбор через `RB_TRANSPORT`):

- **`stdio`** (по умолчанию) — по одному серверу на хост, запускает сам хост.
  Обычно руками не запускается (см. `mcp_config.json` ниже).
- **`streamable-http`** / **`sse`** — один локальный сервер, много клиентов: один
  процесс → **одна загруженная модель эмбеддингов на всех** (меньше RAM, чем в
  stdio, где каждый хост поднимает свою копию). Клиенты подключаются к
  `http://127.0.0.1:8082/mcp` (для `sse` — эндпоинт `/sse`, только legacy).
  Слушает только `localhost`; аутентификации нет — пока сервер запущен, любой
  локальный процесс может к нему обращаться.

> ⚠️ **Не привязывайте сервер к внешнему интерфейсу.** По умолчанию `RB_HOST` =
> `127.0.0.1` (только localhost). Если выставить `RB_HOST=0.0.0.0`, управление
> устройством — включая прошивку и стирание flash — станет доступно из сети без
> всякой авторизации. Для доступа извне поднимайте аутентифицирующий обратный
> прокси.

## Подключение в `mcp_config.json`

Раздел [«Быстрый старт с нуля»](#быстрый-старт-с-нуля) уже показывает конкретно
Cline. Здесь — общий формат и другие хосты/транспорты.

### stdio через `uv tool install` (рекомендуется)

```bash
uv tool install redbees-modem-mcp
```

```json
{
  "mcpServers": {
    "redbees-modem": {
      "command": "redbees-modem-mcp",
      "args": []
    }
  }
}
```

Обновление до новой версии не автоматическое: `uv tool upgrade redbees-modem-mcp`.

### stdio через uvx (эфемерно, без установки)

Не требует отдельного шага установки, но каждый запуск резолвит окружение
заново (правда, из уже скачанного кэша — не по сети) и не переиспользует venv
из `uv tool install`:

```json
{
  "mcpServers": {
    "redbees-modem": {
      "command": "uvx",
      "args": ["redbees-modem-mcp"]
    }
  }
}
```

> Если хост пишет «команда не найдена» — укажите полный путь к exe (обычно
> `~/.local/bin/redbees-modem-mcp[.exe]` или `~/.local/bin/uvx[.exe]`) в поле
> `command`. Частая причина — GUI-хост был открыт ДО установки и не видит
> обновлённый PATH; перезапустите хост целиком.

**HTTP/SSE вместо stdio.** Если нужен один общий сервер (одна загруженная модель
на несколько клиентов), подними его отдельно, а хост подключи по URL. Как
поднять — зависит от способа установки:

- **source-install** (клонированный репозиторий + `pip install -e .`): готовые
  лаунчеры в корне проекта — `run_server.ps1` / `run_server.bat` (Windows) или
  `run_server.sh` (Linux/macOS); по умолчанию `streamable-http` на
  `http://127.0.0.1:8082/mcp` (настройки — в блоке НАСТРОЙКИ вверху скрипта);
- **`uv tool install`**: однострочник
  ```powershell
  $env:RB_TRANSPORT="streamable-http"; redbees-modem-mcp
  ```

Затем в `cline_mcp_settings.json` вместо `command`/`args` укажите URL:

```json
{ "mcpServers": { "redbees-modem": { "url": "http://127.0.0.1:8082/mcp" } } }
```

Сервер должен быть **запущен** до подключения хоста. Для legacy-транспорта `sse`
(`RB_TRANSPORT=sse`) эндпоинт — `/sse`.

### stdio из локального venv

Хост запускает сервер **не из твоего активированного venv**, поэтому указывай
**полный путь** к exe (или к python venv + `-m`), а не голое имя:

```json
{
  "mcpServers": {
    "redbees-modem": {
      "command": "D:/PycharmProjects/rb-modem-assistant/.venv/Scripts/redbees-modem-mcp.exe",
      "env": {
        "RB_MODEL_DIR": "D:/PycharmProjects/rb-modem-assistant/models/jina-code-embeddings-0.5b"
      }
    }
  }
}
```

### HTTP (streamable-http)

Сервер поднимаешь сам (лаунчером `run_server.*` или вручную), а клиент
подключаешь к URL `http://127.0.0.1:8082/mcp`. **Как именно — зависит от клиента:**

- **Claude Code / клиенты с нативной поддержкой HTTP** (`~/.claude.json`) —
  прямое поле `url`:

  ```json
  { "mcpServers": { "redbees-modem": { "type": "http", "url": "http://127.0.0.1:8082/mcp" } } }
  ```

- **Claude Desktop** — его `claude_desktop_config.json` понимает **только
  stdio-формат** (`command`/`args`/`env`); полей `url`/`serverUrl`/`type` он не
  читает. Подключение к HTTP-серверу — через мост `mcp-remote` (нужен Node/npx),
  который оборачивает HTTP в stdio:

  ```json
  {
    "mcpServers": {
      "redbees-modem": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "http://127.0.0.1:8082/mcp"]
      }
    }
  }
  ```

  Сервер (`run_server`) должен быть **запущен** до старта Claude Desktop.
  Альтернатива без JSON — добавить URL как Custom Connector в Settings →
  Connectors. Если HTTP не нужен, проще подключить сервер напрямую по stdio (см.
  разделы выше) — тогда Claude Desktop сам его запускает и держать `run_server`
  не надо.

## Возможности

### Генерация Lua — два шага с одобрением плана

1. `create_lua_script(task)` — **Архитектор**: сжатый под токен-бюджет контекст из
   базы знаний + план / альтернативы / вопросы / риски. Кода нет; модель ждёт
   одобрения пользователя.
2. `implement_plan(task, approved_plan)` — роли **Кодер → (Верификатор ⇄
   Рефлектор) ×≥2**: код по плану (без комментариев, пояснения отдельной секцией),
   затем итеративные проверки и правки через `validate_lua_script`.

Прошивка исполняет **Lua 5.5** — по конструкциям языка применим официальный мануал
<https://www.lua.org/manual/5.5/>. Полный текст мануала включён в корпус базы
знаний (386 функций отдельными секциями), так что `query_documentation` отвечает
и на вопросы по языку (синтаксис, `string`/`table`/`math`, метатаблицы,
корутины); API устройства — только из базы знаний.

Прочие инструменты генерации/поиска: `validate_lua_script` (синтаксис через `lupa`
с реальным Lua 5.5 — той же версии, что на устройстве;
правила Zephyr: Watchdog в `while`/`repeat`, запрет `os`/`io`, конкатенация строк в
циклах, запрет комментариев), `query_documentation`, `compress_context`,
`list_api_channels`, `list_examples`, `view_example`, `shell_api_reference`,
`settings_api_reference`.

### Доступ к устройству по SMP (полный mcumgr)

Кроссплатформенно, на базе [`smpclient`](https://intercreate.github.io/smpclient/)
(без `mcumgr.exe`). Три транспорта: **serial** (`port=COM5`), **BLE**
(`ble_address`/`peer_name`), **UDP** (`host`, IPv4/IPv6). Подсистемы:

- `smp_image` — `list` / `upload` / `erase` / `test` / `confirm` / `ic_upload`.
  У `upload` — `slot` (номер образа), `upgrade` (принять только более новую версию),
  `use_sha` (для малого MTU); у `erase` — выбор `slot`. `ic_upload` — загрузка через
  вендорную группу Intercreate (нужна её поддержка в прошивке);
- `smp_fs` — `upload` / `download` (size + SHA-256) / `status` / `hash` (+ `off`/`length`
  для хеша диапазона байт) / `hash_types` / `close`;
- `smp_os` — `reset` (+ `force`; `boot_mode` для перезагрузки в загрузчик/serial-recovery
  — нужна поддержка в прошивке) / `echo` / `taskstat` / `mpstat` / `datetime` /
  `datetime_write` / `bootloader` / `mcumgr_params` / `appinfo`;
- `smp_settings` — `read` / `write` / `delete` / `save` / `commit` / `load`
  (`value_type` = str/int/bool/hex, ключи из `SETTINGS_API_*.md`);
- `smp_shell` — shell-команды устройства (из `SHELL_API_*.md`);
- `smp_stat` — статистика; `smp_enum` — перечислить поддерживаемые SMP-группы
  (`details` принимает фильтр `groups`);
- `smp_zephyr erase_storage` — стереть раздел storage (необратимо).

Идентификация: `list_serial_ports`, `scan_ble_devices` (фильтр по SMP Service
UUID), `identify_device`, `discover_devices` (дедуп одного устройства по приоритету
serial→ble→udp). Развёртывание/диагностика: `upload_lua_script`, `read_serial_logs`,
`test_script_on_device`, `diagnose_device`, `hardware_reset_serial`.

### Прошивка (esptool)

`esptool_version`, `flash_bootloader` (→ `0x0`), `flash_application` (→ `0x20000`),
`flash_firmware` (любой адрес), `erase_flash`.

### Безопасность — по умолчанию превью

Все операции записи (прошивка, `smp_*` upload/erase/reset/write/delete/commit/
datetime_write/erase_storage, `upload_lua_script`) без `confirm=true` возвращают
**превью** и ничего не делают. Тесты и диагностика на устройстве — только по явному
запросу пользователя. Детали — в [playbook](redbees_modem_mcp/data/DEVICE_PLAYBOOK.md),
который сервер отдаёт хосту как `instructions`.

## Семантический поиск (обязателен)

Семантический RAG **всегда включён** — без базы знаний сгенерированный Lua
галлюцинировал бы. Пользователю **поставляется готовый numpy-стор** (bundled в
пакете); приватный корпус исходников — нет. Keyword-поиск по bundled `examples/`
остаётся лишь как дополнение к контексту, не как самостоятельный фолбэк. Если стор
не загрузился, RAG-инструменты возвращают громкий баннер `SEMANTIC RAG UNAVAILABLE`,
а не молча деградируют.

Модель эмбеддингов (jina-code-embeddings) скачивается при первом запуске (в
пользовательский кэш или `RB_MODEL_DIR`). Стор — обычная numpy-матрица
(`vectors.npy` + `docs.json`), **не** chromadb: у chromadb персистентный HNSW-индекс
ненадёжно перечитывается между процессами.

> Пересборка стора — шаг **мейнтейнера**: `python tools/admin_builder.py` эмбеддит
> приватный корпус и пишет только векторы + имена файлов (без текста исходников).
> Модель переключается в `redbees_modem_mcp/config.py` (`MODEL_NAME`) — сменил
> модель, пересобери стор. На Windows держи `RB_OMP_THREADS=1` (многопоточность
> может давать segfault этой модели).

## Переменные окружения

Строго обязательных нет — у всех есть значения по умолчанию (стор bundled, модель
скачивается сама). Все переменные также выписаны в блоке НАСТРОЙКИ лаунчеров
`run_server.*` (обязательные — активны, опциональные — закомментированы).
На практике задаёшь переменные транспорта для HTTP-режима и, при необходимости,
`RB_MODEL_DIR` / `RB_VECTOR_DB_DIR` на свою модель/стор.

| Переменная | По умолчанию | Назначение |
|---|---|---|
| `RB_TRANSPORT` | `stdio` | `stdio` \| `streamable-http` \| `sse` |
| `RB_HOST` | `127.0.0.1` | host для HTTP-транспортов |
| `RB_PORT` | `8082` | порт для HTTP-транспортов |
| `RB_TOOLSET` | `full` | `full` = все инструменты; `lua` = только 8 инструментов генерации/проверки Lua + доки (меньше контекста, лучше выбор инструментов у слабых LLM) |
| `RB_MODEL_NAME` | `jina-code-embeddings-0.5b` | модель эмбеддингов (также в `config.py`); перебивается `RB_MODEL_DIR`. **Должна совпадать с моделью, которой собран стор** — bundled-стор собран `0.5b` |
| `RB_MODEL_DIR` | `./models/<name>` или кэш | папка локальной модели (полный путь; **главнее `RB_MODEL_NAME`**). Скачивается, если её нет |
| `RB_HF_REPO_ID` | `jinaai/<RB_MODEL_NAME>` | HF-репозиторий для автоскачивания модели; нужен только для не-jina моделей |
| `RB_VECTOR_DB_DIR` | bundled `data/vector_store` | папка numpy-стора |
| `RB_OMP_THREADS` | `1` | потоки CPU для эмбеддинга; **на Windows держать `1`** (многопоток может дать segfault) |
| `RB_EXAMPLES_DIR` | bundled `data/examples` | папка Lua-примеров и API-доков |
| `RB_DOC_TOKEN_BUDGET` | `6000` | токен-бюджет сжатия контекста (единственный способ задать бюджет: клиент передать его не может) |
| `HF_TOKEN` | — | токен HuggingFace для скачивания модели (если нужно) |

## Разработка

```bash
pip install -e .            # RAG-зависимости теперь в core
python tests/run_all.py     # офлайн-тесты
python -m redbees_modem_mcp # запуск из исходников
```

### Сборка векторного стора (только для мейнтейнера)

Сборщик `tools/admin_builder.py` и приватный корпус `secret_source_codes/` **не
входят** в дистрибутив и недоступны пользователям. Сборка из исходников (семантические
зависимости уже в core, ничего доп. не нужно):

```powershell
$env:RB_SOURCE_DIR="./secret_source_codes"                       # приватный .lua/.md корпус
$env:RB_MODEL_DIR="./models/jina-code-embeddings-0.5b"           # та же локальная модель
.\.venv\Scripts\python.exe tools/admin_builder.py                # → redbees_modem_mcp/data/vector_store
```

Стор строится только на локальной модели (офлайн). По умолчанию сборщик пишет
результат (vectors.npy + docs.json — только векторы и имена файлов, без текста
корпуса) прямо в `redbees_modem_mcp/data/vector_store` — оттуда он попадает в
wheel и сервер находит его без переменных окружения. `RB_VECTOR_DB_DIR`
переопределяет путь и у сборщика, и у сервера (для экспериментов).

## Устранение проблем

**`uvx --version` → «команда не найдена» (после установки uv).**
Закройте терминал и откройте заново — установщик прописывает `uv` в PATH только
для новых окон. Не помогло: перезагрузите компьютер.

**Хост пишет «redbees-modem-mcp not found» при запуске сервера.**
GUI-хост (Cline, Claude Desktop и т.п.) не видит PATH, обновлённый после
установки uv/сервера — особенно если он был открыт ДО этого. Варианты:
- перезапустите хост целиком (не только окно, а процесс) и попробуйте снова;
- укажите полный путь к файлу в поле `command`. Обычно это
  `C:\Users\<имя>\.local\bin\redbees-modem-mcp.exe` (Windows) или
  `/home/<имя>/.local/bin/redbees-modem-mcp` (Linux).

**Хост долго стартует и краснеет / отваливается по таймауту.**
Скорее всего сервер и модель не были скачаны заранее (см.
[шаг 4](#шаг-4-скачать-mcp-сервер) и [шаг 5](#шаг-5-скачать-поисковую-модель)) —
сервер качает себя и модель прямо на старте. Выполните в терминале
`uv tool install redbees-modem-mcp`, затем `redbees-modem-mcp-download-model`,
дождитесь конца, затем в хосте перезапустите сервер.

**Модем не виден / нет нужного COM-порта.**
- Windows: проверьте кабель и «Диспетчер устройств»; при необходимости поставьте
  драйвер USB-UART.
- Linux: добавьте себя в группу доступа к порту и перелогиньтесь:
  ```bash
  sudo usermod -aG dialout $USER
  ```

**Загрузка модели идёт очень долго / обрывается.**
Это большая загрузка (~1 ГБ модель + ~2 ГБ зависимости сервера при самом первом
запуске). Проверьте интернет и свободное место на диске, затем запустите
`redbees-modem-mcp-download-model` ещё раз — уже скачанное не качается заново.

### `WinError 1114` при инициализации `c10.dll`

Если при запуске сервера или скачивании модели в консоли ошибка:
`[WinError 1114] Произошёл сбой в программе инициализации DLL. Error loading "...c10.dll"...`

По умолчанию PyTorch ставит CUDA-сборку, которая конфликтует с гибридной графикой
(Intel + NVIDIA) или планами энергосбережения Windows.

**Решение:** переустановить CPU-сборку PyTorch в venv:
```bash
pip install torch --index-url https://download.pytorch.org/whl/cpu --force-reinstall
```

### Segfault при эмбеддинге / `SEMANTIC RAG UNAVAILABLE`

Многопоточность OpenMP/MKL на Windows может ронять модель. Держи `RB_OMP_THREADS=1`
(значение по умолчанию). Сервер и сборщик уже фиксируют переменные OMP/MKL и
пред-импортируют torch до нативных модулей устройства.

## Лицензия

[Apache-2.0](LICENSE).
