redbees-modem-mcp

MCP-сервер для модема Redbees (Zephyr RTOS): пошаговая генерация и проверка Lua-скриптов, полный доступ к устройству по SMP (mcumgr) через serial/BLE/UDP-DTLS и прошивка через 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
3. Шаг 2. Установить расширение Cline
4. Шаг 3. Установить uv
5. Шаг 4. Скачать MCP-сервер
6. Шаг 5. Скачать поисковую модель
7. Шаг 6. Прописать MCP-сервер в Cline
8. Шаг 7. Подключить модель ИИ (LLM) в Cline
9. Шаг 8. Проверка

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

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

Две разные «модели» не перепутайте:

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

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

Windows:

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

Linux:

# 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 -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Linux:

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):

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

"RB_TRANSPORT": "stdio" прописан не для красоты. Сервер выбирает stdio только потому, что переменной нет, а блок env хоста накладывается поверх унаследованного окружения. Если RB_TRANSPORT=streamable-http когда-нибудь окажется в системных переменных (естественный шаг, когда гоняешь HTTP-сервер), то без этой строки хост запустит сервер, а тот вместо ответа на stdin поднимет HTTP-порт — и хост отвалится по таймауту.

Команда redbees-modem-mcp — тот же исполняемый файл, который установил шаг 4 (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.

---

Развёртывание на другом ПК

Клонировать репозиторий не нужно: и код, и база знаний (векторный стор + 48 Lua-примеров) целиком лежат в wheel на PyPI. По сети докачивается только модель эмбеддингов (~1 ГБ, один раз). Нужен uv — если его нет, см. Шаг 3.

Если сервер запускает MCP-хост (stdio)

uv tool install redbees-modem-mcp
redbees-modem-mcp-download-model

Дальше — блок в mcp_config.json хоста, см. stdio через uv tool install. Вторая команда не обязательна, но без неё модель качается при первом запросе, и хост может отвалиться по таймауту.

Если нужен локальный HTTP-сервер

uv tool install redbees-modem-mcp
RB_TRANSPORT=streamable-http RB_PORT=8082 redbees-modem-mcp

PowerShell:

uv tool install redbees-modem-mcp
$env:RB_TRANSPORT="streamable-http"; $env:RB_PORT="8082"; redbees-modem-mcp

Клиенты подключаются к http://127.0.0.1:8082/mcp. Лаунчеры run_server.* и .env тут не участвуют — они живут в репозитории, а переменные задаются прямо в окружении. Если хочется именно конфиг-файл, ставь из исходников и запускай run_server.*.

Linux: PyPI тянет CUDA-сборку torch

На Linux torch с PyPI приезжает с CUDA — это +15 пакетов nvidia-* и лишние ~3 ГБ, которые серверу не нужны: эмбеддинги считаются на CPU. Ставь в venv с явным CPU-бэкендом:

uv venv
UV_TORCH_BACKEND=cpu uv pip install redbees-modem-mcp
RB_TRANSPORT=streamable-http .venv/bin/redbees-modem-mcp

На Windows и macOS обход не нужен: колесо torch с PyPI там и так без CUDA, хватает обычного uv tool install.

UV_TORCH_BACKEND действует на uv pip install, но не заявлена для uv tool install — поэтому здесь venv, а не tool. Установка из репозитория (git+…) тоже даёт CPU-сборку: она закреплена в pyproject.toml через [tool.uv.sources], и на исходники это правило распространяется, в отличие от метаданных на PyPI.

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

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

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

uvx redbees-modem-mcp

uvx (часть uv) сам скачивает и запускает пакет эфемерно — отдельный venv не создаётся, но каждый запуск заново резолвит окружение (из уже скачанного кэша, не по сети).

Через pip

pip install redbees-modem-mcp

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

Рекомендуется использовать uv — он автоматически настроит .venv и установит легковесную CPU-сборку PyTorch:

uv sync                 # рекомендуемый способ: быстрое развёртывание окружения
# или классический способ:
pip install -e .        # RAG-зависимости теперь в core (torch и пр. включены)

Запуск

Проще всего — готовые скрипты-лаунчеры в корне проекта: поднимают локальный HTTP-сервер (streamable-http) на http://127.0.0.1:8082/mcp. Сами находят среду Python (uv run, затем .venv, затем системный) — отдельный exe не нужен.

Все настройки живут в .env рядом с лаунчерами; шаблон со всеми переменными и комментариями — .env.example. При первом запуске лаунчер создаст .env из шаблона сам. .env в git не коммитится (в нём локальные пути и HF_TOKEN) — коммитится только .env.example.

.env — приоритетный источник настроек: сервер загружает его с переопределением переменных окружения (load_dotenv(override=True)). Настройки из .env надежно перекрывают любые унаследованные системные переменные ОС, предотвращая конфликты (например, со старым RB_MODEL_DIR на удаленную папку). Следствие: разовый RB_PORT=9000 ./run_server.sh не сработает — правьте .env.

.\run_server.ps1          # Windows PowerShell
run_server.bat            # Windows: двойной клик или cmd

./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, установка из исходников):

# 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-режим без лаунчера (лаунчер делает то же, взяв значения из .env):
$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 (рекомендуется)

uv tool install redbees-modem-mcp

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

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

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

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

{
  "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 (настройки — в .env, шаблон .env.example);
• uv tool install: однострочник

  $env:RB_TRANSPORT="streamable-http"; redbees-modem-mcp
  

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

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

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

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

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

{
  "mcpServers": {
    "redbees-modem": {
      "command": "D:/PycharmProjects/rb-modem-assistant/.venv/Scripts/redbees-modem-mcp.exe",
      "env": {
        "RB_TRANSPORT": "stdio",
        "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:

  { "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:

  {
    "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: обязательная передача CPU в while/repeat, запрет os/io, конкатенация строк в циклах, запрет комментариев), query_documentation, compress_context, list_api_channels, list_examples, view_example, shell_api_reference, settings_api_reference.

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

Кроссплатформенно, на базе smpclient (без mcumgr.exe). Три транспорта: serial (port=COM5), BLE (ble_address/peer_name, системное pairing-окно для шестизначного passkey), UDP/DTLS-PSK (host, IPv4/IPv6). Для UDP передай security={"dtls_psk_identity":"<eFuse factory serial, decimal>","dtls_psk":"<hex>"} либо задай RB_SMP_DTLS_PSK_ID/RB_SMP_DTLS_PSK_HEX; ключ в отчёты не выводится. PSK-ID не настраивается отдельно: это заводской серийный номер модема, записанный в eFuse и передаваемый десятичной строкой. Явный udp-plain оставлен только для старых dev-сборок. Подсистемы:

• 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_boot — firmware update protocol 2: status / apply_update / confirm / confirm_mode / factory / clear_factory / slot;
• smp_wait_management_ready — после update/reboot ждёт строку boot: management ready (protocol=2, ...) на COM и подтверждает готовность успешным app_boot status; для BLE/UDP использует ограниченные повторы;
• smp_settings — read / write / delete / save / commit / load (value_type = str/int/bool/hex, ключи из SETTINGS_API_*.md). Защищённые write-only ключи настраиваются профильными командами: ble/passkey через app_smp ble passkey, smp/psk через app_smp udp psk, а boot/confirm_mode через smp_boot confirm_mode;
• 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.

Штатное MCU OTA для новой прошивки: smp_image list → загрузка *_smp.bin → smp_boot apply_update <auto|manual> → smp_wait_management_ready → smp_boot status → при manual-политике smp_boot confirm. Старую пару smp_image test + smp_os reset применять нельзя: apply_update атомарно сохраняет политику, выставляет TEST, очищает update/factory-латчи и сам планирует перезагрузку. *_smp.bin обновляет только приложение; миграция MCUboot требует однократной полной сервисной прошивки.

Прошивка может одновременно запустить до четырёх независимых файлов /scripts/*.lua: у каждого отдельный Lua state, heap и поток Zephyr. Это подходит только для действительно независимых долгоживущих задач; обмен между файлами возможен лишь через уже объявленные прошивкой каналы ZBus. В остальных случаях предпочтительнее один событийный цикл или корутины. Каждый файл проверяется отдельно, а wait_msg()/zephyr.msleep() нужны для отдачи CPU, а не для «кормления» Lua-watchdog.

Прошивка (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, который сервер отдаёт хосту как 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, модель скачивается сама). Задаются они в .env (шаблон — .env.example, формат и правила приоритета описаны в его шапке); лаунчеры run_server.* читают именно его. На практике задаёшь переменные транспорта для HTTP-режима и, при необходимости, RB_MODEL_DIR / RB_VECTOR_DB_DIR на свою модель/стор.

При запуске в stdio-режиме .env НЕ участвует: там сервер стартует сам MCP-хост, и переменные надо передавать через блок env в mcp_config.json.

Переменная	По умолчанию	Назначение
RB_TRANSPORT	stdio	stdio | streamable-http | sse
RB_HOST	127.0.0.1	host для HTTP-транспортов
RB_PORT	8082	порт для HTTP-транспортов
RB_SESSION_IDLE_TIMEOUT	0 (выкл.)	секунды простоя, после которых streamable-http сессия закрывается. Выключено по умолчанию: закрытая сессия заставит клиент переинициализироваться. Имеет смысл (напр. 3600) на сервере, который живёт сутками — добирает висящие сессии, которые оставляют зонды клиентов
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	токен-бюджет сжатия контекста (единственный способ задать бюджет: клиент передать его не может)
RB_SMP_TIMEOUT	5.0	секунды на один SMP-запрос к устройству (у smpclient по умолчанию 2.5 — этого не хватает app_sysinfo health и первым секундам после большой fs-передачи). Тот же потолок применяется к мёртвому эндпоинту, так что слишком большое значение растягивает и отказы. Скан портов в discover_devices всегда пробует коротко (2.5 с)
RB_SERIAL_WRITE_TIMEOUT	5.0	секунды на блокирующую запись в COM-порт (защита от зависшего/выдернутого порта)
RB_SMP_DTLS_PSK_ID	—	DTLS-PSK identity для одного закреплённого устройства: заводской serial десятичной строкой; можно передавать на вызов в security
RB_SMP_DTLS_PSK_HEX	—	DTLS PSK, 4–32 байта в hex (штатно 16); хранить только в .env, не коммитить
HF_TOKEN	—	токен HuggingFace для скачивания модели (если нужно)

Разработка

uv sync                     # рекомендуемый способ (или pip install -e .)
python tests/run_all.py     # офлайн-тесты
python -m redbees_modem_mcp # запуск из исходников

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

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

$env:RB_SOURCE_DIR="./secret_source_codes"                       # приватный .lua/.md корпус
$env:RB_MODEL_DIR="./models/jina-code-embeddings-0.5b"           # та же локальная модель
$env:RB_EMBED_BATCH_SIZE="8"                                     # размер пакета, допустимо 1..64
.\.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 и шаг 5) — сервер качает себя и модель прямо на старте. Выполните в терминале uv tool install redbees-modem-mcp, затем redbees-modem-mcp-download-model, дождитесь конца, затем в хосте перезапустите сервер.

Модем не виден / нет нужного COM-порта.

• Windows: проверьте кабель и «Диспетчер устройств»; при необходимости поставьте драйвер USB-UART.
• Linux: добавьте себя в группу доступа к порту и перелогиньтесь:

  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:

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.