Serial Bridge

Serial Bridge — это Hub, который разделяет две последовательные консоли между локальным оператором и MCP-агентами. Он не привязан к конкретной ОС: установите пакеты Python из requirements.txt и запускайте на любом хосте с Python 3.10+. Hub находится в пакете serial_bridge/; запускается командой python -m serial_bridge или через корневой shim-файл app.py.

Установка и запуск

Рекомендуется Python 3.10 или новее.

python -m pip install -r requirements.txt
python -m serial_bridge

Примеры с shell-командами ниже используют PowerShell ($env:NAME = "..."). В bash или zsh задайте те же имена с помощью export NAME=....

Hub открывает ваш браузер на консоли по адресу http://127.0.0.1:8765/, как только начинает прослушивание. Корневой shim-файл app.py эквивалентен. Чтобы запустить без открытия вкладки браузера:

$env:SERIAL_BRIDGE_OPEN_UI = "off"
python -m serial_bridge

Или передайте --no-open-ui. Используйте --open-ui, чтобы принудительно открыть, когда окружение это отключает. Если SERIAL_BRIDGE_OPEN_UI не задан, открытие происходит по умолчанию; только 0, false, no и off (без учёта регистра) отключают его.

При первом запуске Hub автоматически генерирует Access Token в файл serial_bridge.token рядом с файлом конфигурации Port Binding (путь можно переопределить через SERIAL_BRIDGE_TOKEN_FILE). Не коммитьте файл с секретами.

Откройте Setup (http://127.0.0.1:8765/setup) на хосте Hub, чтобы скопировать URL Hub, посмотреть Access Token, ротировать его и вставить фрагмент mcpServers для Cursor. Секреты Setup (открытый текст токена, Rotate и фрагмент с секретом) видны только на loopback (127.0.0.1 / ::1).

В качестве альтернативы установите SERIAL_BRIDGE_TOKEN перед запуском Hub и передайте тот же секрет MCP-клиенту. Переменная окружения переопределяет файл секретов на время жизни процесса; Rotate по-прежнему перезаписывает файл, но предупреждает, пока переменная окружения не снята или Hub не перезапущен без неё.

Аутентификация MCP обязательна даже с loopback. Не помещайте токен в систему контроля версий, статические файлы фронтенда, URL или логи.

Hub прослушивает 0.0.0.0:8765, поэтому он доступен из локальной сети. Используйте соответствующий межсетевой экран хоста и надёжный токен. Удалённые агенты не могут менять режимы или Port Bindings.

MCP

Используйте Setup (/setup) на хосте Hub для конфигурации Cursor копированием и вставкой. Ручная настройка:

Настройте потоковое HTTP MCP-подключение агента:

URL: http://<hub-host>:8765/mcp
Authorization: Bearer <SERIAL_BRIDGE_TOKEN>

Используйте /mcp точно; веб-интерфейс находится на /. MCP-сервер предоставляет:

• serial_status: чтение текущего режима и Port Binding каждого Target, состояния открытия и подсказки занятости.

• serial_exec: отправка одной текстовой команды и захват вывода до паузы бездействия, необязательного совпадения с prompt или 60-секундного тайм-аута.

• serial_send: отправка текстовой строки или Raw Payload без ожидания вывода.

Чтобы проверить статус и Exec:

1. Откройте веб-интерфейс локально и переключитесь в Bridge Mode.

2. Подключите MCP-клиент к указанному выше URL с заголовком Bearer.

3. Вызовите serial_status без аргументов и подтвердите, что mode равен bridge, а нужный Target открыт.

4. Вызовите serial_exec с {"target":"linux","cmd":"uname -a"} или {"target":"rtos","cmd":"help"}.

5. Если устройство имеет стабильный prompt, при необходимости передайте prompt; установите prompt_is_regex в true только если значение prompt является регулярным выражением.

Exec принимает имена Target linux и rtos, а не имена последовательных устройств. Он возвращает захваченный output плюс флаги timed_out, truncated и aborted.

Вывод Exec и транскрипты live/*.log — это обычный текст с удалёнными ANSI-escape-последовательностями. Веб-интерфейс вместо этого интерпретирует escape-последовательности и показывает цвета устройства.

Port Binding

Port Binding назначает Target пути к последовательному устройству и скорости в бодах. Встроенные значения по умолчанию — в стиле Windows (linux на COM3, rtos на COM6, оба 115200); в Linux или macOS задайте пути, например /dev/ttyUSB0.

Переопределите значения по умолчанию перед запуском с помощью переменных окружения:

$env:SERIAL_BRIDGE_LINUX_PORT = "COM8"
$env:SERIAL_BRIDGE_LINUX_BAUD = "57600"
$env:SERIAL_BRIDGE_RTOS_PORT = "COM9"
$env:SERIAL_BRIDGE_RTOS_BAUD = "115200"
python -m serial_bridge

Эквивалентные флаги CLI: --linux-port, --linux-baud, --rtos-port и --rtos-baud. SERIAL_BRIDGE_CONFIG или --config выбирает сохранённый JSON-файл. Порядок загрузки: встроенные значения по умолчанию, затем значения из окружения/CLI, затем сохранённый файл; сохранённые значения веб-интерфейса имеют приоритет.

Только Operator может редактировать Port Bindings, и только в CRT Mode, пока Hub освободил порты. Веб-интерфейс перечисляет обнаруженные последовательные порты в раскрывающемся списке для каждого Target; используйте Scan для повторного перечисления после подключения адаптера. Изменения, внесённые в веб-интерфейсе, сохраняются после перезапуска.

Live Directory

Live Directory — это каталог, в который Hub записывает журналы сеансов Bridge для каждого Target и bridge_status.json. По умолчанию это <app-dir>/live/ рядом с корнем проекта (та же директория, что и serial_bridge.json и корневой shim-файл app.py).

Переопределите перед запуском с помощью:

$env:SERIAL_BRIDGE_LIVE_DIR = "D:\logs\serial-bridge"
python -m serial_bridge

Или передайте --live-dir. Порядок загрузки совпадает с Port Binding: встроенное значение по умолчанию, затем окружение/CLI, затем сохранённый файл конфигурации; сохранённые значения веб-интерфейса имеют приоритет.

Каждый раз, когда Operator входит в Bridge Mode, Hub создаёт новые файлы журналов с именами <TargetName>-YYYY-MM-DD-HHMMSS.log (локальное время, 24-часовой формат). Второй сеанс Bridge создаёт новые файлы; старые журналы остаются на месте и не переносятся при изменении Live Directory или переименовании Target.

Изменить Live Directory в веб-интерфейсе можно только в панели Bindings в CRT Mode (тот же путь записи только через loopback, что и Port Binding). В нижнем колонтитуле отображается настроенный каталог и имена файлов журнала текущего сеанса, когда они назначены.

Bridge Mode и CRT Mode

• Bridge Mode: Hub владеет настроенными последовательными портами. Operator и агенты могут отправлять команды и наблюдать одни и те же живые транскрипты.

• CRT Mode: Hub освобождает порты для SecureCRT или другого эксклюзивного последовательного клиента. MCP Exec и Send завершаются ошибкой, пока Operator не вернётся в Bridge Mode.

Отключите SecureCRT перед входом в Bridge Mode. Переключение в CRT Mode прерывает выполняющийся Exec и может вернуть частичный вывод.

Предупреждение о Raw Send

serial_send с raw_hex записывает произвольные байты без обрамления текстовыми строками или автоматического перевода строки. Это полная мощность консоли: управляющие байты могут прервать загрузку, завершить процессы, изменить состояние устройства или сделать сеанс неотзывчивым. Предпочитайте serial_exec для команд и используйте Raw Payloads только когда точная последовательность байтов и влияние на устройство понятны.