Bridge

SXL Studio Bridge — небольшая программа, которая запускается на вашем компьютере и связывает работающий плагин SXL Studio с внешними инструментами: Cursor, Claude Desktop и другими MCP-клиентами, а также скриптами. Через неё AI-агент может читать и менять токены, переменные, стили, композиции и данные в открытом файле Figma. Та же программа обслуживает Local Workspace и Local Storage.

#Требования

Для нескольких вкладок, управления Figma Desktop и опасных команд, которые включаются сами, нужны Bridge 1.11 и плагин 2.9.6.

Bridge слушает только локальный адрес 127.0.0.1: к нему нельзя подключиться с другого компьютера.

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

npm install -g @sxl-studio/bridge

sxl-bridge

Bridge занимает один порт, по умолчанию 37830. На нём работают подключение плагина, MCP-адрес http://127.0.0.1:37830/mcp и HTTP-запросы http://127.0.0.1:37830/api/.... Если порт занят, задайте другой через переменную окружения:

BRIDGE_PORT=39999 sxl-bridge

Тот же порт потом нужно указать в плагине и в настройках MCP-клиента.

Проверка, что программа запущена:

sxl-bridge health

#Подключение плагина: Remote Connect

Remote Connect включается сам. При каждом запуске в режиме Design плагин подключается к Bridge на сохранённом порту и ждёт команд в фоне. Интерфейс плагина остаётся доступным, нажимать ничего не нужно. Если Bridge не запущен, плагин повторяет попытку: первая — через секунду, дальше всё реже, но не реже раза в 30 секунд. Он подключается, как только Bridge появится. Связь восстанавливается сама после перезапуска Bridge и после горячей перезагрузки сборки для разработки. Нужна лицензия Pro Plus.

Чтобы увидеть подключение:

1. В подвале плагина нажмите кнопку Remote Connect. Плагин свернётся в компактную строку с состоянием подключения.
2. Разверните строку кнопкой со стрелками, чтобы открыть окно подключения. В нём поле Port, поле Token для защищённого режима и переключатель Allow destructive commands.
3. Состояние Connected — Waiting for commands означает, что агент может отправлять команды.

Компактная строка Remote Connect в подвале плагина: состояние подключения, Disconnect и кнопка разворота.

Окно Remote Connect: порт, токен, идентификаторы сессии и клиента, переключатель Allow destructive commands.

Пока открыто окно подключения, вкладки плагина скрыты. Disconnect отключает Remote Connect до следующего запуска плагина и возвращает обычный интерфейс. Плагин запоминает порт между сессиями.

#Опасные команды

Опасные команды: удаление слоёв, переменных и коллекций, сброс идентификаторов синхронизации и hard pull. Они включаются сами, как только Bridge 1.11 или новее ответит на подключение, кроме защищённых файлов. Более старый Bridge не различает файлы, поэтому с ним опасные команды остаются выключенными, пока их не включат явно. Даже с разрешением агент обязан явно подтверждать каждую опасную команду.

В защищённом файле сессия начинается с выключенными опасными командами. Включить их можно двумя способами:

• переключателем Allow destructive commands;
• командой агента set_session_policy с подтверждением файла: в confirmFile передаётся ключ или имя этого файла.

Файл считается защищённым, если в списке есть любой из его ключей. Он же считается защищённым, если плагин не может прочитать его ключ или сам список. Защиту ставит команда protect_file: для текущего файла, по ключу или по ссылке на файл. Снять её можно той же командой с protect: false и confirmFile — ключом или именем файла. Защита, поставленная из другой вкладки, выключает опасные команды в этом файле перед следующей опасной командой. Список хранится на этом компьютере и действует во всех файлах. Защищайте файлы с опубликованной библиотекой. Выбор, сделанный командой или переключателем, действует до конца сессии.

Перед export_variables можно проверить экспорт через preview_export_variables. Sort упорядочивает стили и их папки без смены ID; переставлять существующие коллекции, моды и переменные публичный API Figma не позволяет. Эти MCP-инструменты игнорируют старую настройку allowDestructiveReorder. Удаление осиротевших объектов остаётся отдельным опасным действием. См. Экспорт переменных и стилей.

#Защищённый режим

Если Bridge запущен с переменной BRIDGE_AUTH_TOKEN, все подключения должны предъявить тот же токен: введите его в поле Token окна Remote Connect, в форму подключения Local Storage и в настройки MCP-клиента.

BRIDGE_AUTH_TOKEN=my-secret sxl-bridge

#Несколько файлов и управление Figma

Bridge 1.11 держит плагин сразу в нескольких вкладках Figma. Команда уходит в один файл. Он выбирается в таком порядке:

1. Явная цель: targetFileKey у любого MCP-инструмента, который работает с плагином, или fileKey в теле POST /api/command. Ответ показывает, куда ушла команда: bridgeTarget в MCP, target в HTTP.
2. Текущий выбор — последнее из двух действий: выбор файла через select_plugin_session (по ключу, имени или ссылке) и открытие файла агентом через figma_open_file, figma_run_plugin или restart_plugin. Явный выбор отменяет файлы, открытые раньше и ещё не подключившиеся.
3. Первый подключившийся незащищённый файл.
4. Единственный подключённый незащищённый файл.

Если выбрать файл нельзя, команда отклоняется с ambiguous-target. Защищённый файл сам не выбирается: открытие файла и запуск в нём плагина его тоже не выбирают. Команды попадают в него только по явной цели или после select_plugin_session. Когда подключено несколько файлов, передавайте targetFileKey в каждой записи. Список подключённых файлов и текущую цель показывает list_plugin_sessions. Пока выбранный файл переподключается, например при перезапуске плагина, команда ждёт его до 20 секунд.

Figma Desktop на macOS агент ведёт сам:

Для запуска плагина через меню процессу, в котором работает Bridge, нужно разрешение macOS: System Settings → Privacy & Security → Accessibility. Для Bridge, запущенного как служба, это его программа node, путь к ней показывает figma_desktop_status. Перед нажатием меню Bridge выводит Figma на передний план: в фоне Figma команду меню не выполняет. Открытие файлов и горячая перезагрузка работают без разрешения.

Пока окно Figma скрыто — в другом пространстве, свёрнуто или спрятано, — Figma приостанавливает работу с документом. Apply, Generate и экспорт ждут, хотя на другие команды плагин отвечает. figma_desktop_status показывает, видно ли окно. /api/status сообщает FIGMA_WINDOW_HIDDEN, если команда плагина идёт дольше 20 секунд при скрытом окне. Перед долгой работой выведите файл на экран: это делает figma_open_file.

#Подключение AI-инструмента

Bridge работает по протоколу MCP. Для Cursor добавьте в .cursor/mcp.json:

{
  "mcpServers": {
    "sxl-studio": {
      "url": "http://127.0.0.1:37830/mcp"
    }
  }
}

Другие MCP-клиенты подключаются к тому же адресу. Запускайте Bridge до открытия чата с агентом, иначе инструменты не появятся в списке. Первое, что стоит попросить агента: вызвать get_operator_runbook, он описывает, с чего начинать, и get_plugin_status, он показывает, видит ли Bridge плагин.

#Что может агент

Полный список отдаёт сам Bridge: инструмент list_tools или адрес http://127.0.0.1:37830/api/tools.

Инструменты предпросмотра и аудита ничего не меняют. Инструменты записи принимают dryRun: true для проверки без изменений. Большие ответы Bridge сокращает до сводки, полный вариант можно запросить отдельно.

#Bridge и режимы Figma

#Local Workspace

Bridge читает и записывает файлы токенов и данных в папке на диске для режима Local Workspace и хранит большие файлы Local Storage для Git-подключений. Для этого не нужен Remote Connect: достаточно запущенного Bridge и включённого профиля в настройках синхронизации. Порт и токен задаются на вкладке Local Workspace окна Synchronization settings. Подробнее: Local Workspace и Local Storage.

#Если что-то не работает

#Связанные страницы

• Local Workspace
• Local Storage
• Композиции
• Генерация кода