Русский
Архитектура
Назначение
Компаньон предоставляет MCP-доступ к документам Figma, в которых пользователь открыл плагин Bridge. Всё состояние во время работы находится в памяти на компьютере пользователя.
Компоненты и транспорт
Процесс работает с двумя транспортами:
- STDIO обслуживает MCP.
stdoutпредназначен только для сообщений протокола MCP, а журналы и диагностика выводятся вstderr. - Локальный WebSocket
/bridgeобслуживает плагин Bridge. Он принимает только значения Host127.0.0.1:<port>иlocalhost:<port>.
Жизненный цикл подключения
- MCP-клиент запускает локальный компаньон и устанавливает сессию STDIO.
- Интерфейс плагина открывает
ws://127.0.0.1:<bridge-port>/bridgeс подпротоколомfigma-mcp-bridge.v2. По умолчанию используется порт3846; его можно изменить аргументом MCP-сервера--port <1-65535>. - Плагин отправляет
helloсо случайнымconnection_idи контекстом документа. - Компаньон проверяет сообщение, сохраняет подключение во внутриизменяемом реестре в памяти и отвечает
hello_ack. - MCP-клиент вызывает
list_figma_connections, выбирает активныйconnection_idи передаёт его каждому инструменту документа. - Компаньон последовательно отправляет запросы bridge и сопоставляет ответы по
request_id. - При отключении подключение удаляется, а ожидающие запросы завершаются контролируемой ошибкой.
connection_id обозначает экземпляр запущенного плагина, а не постоянный файл Figma. При замене подключения используется compare-and-swap, поэтому устаревший сокет не может удалить новое активное подключение.
Диагностика сервера
Инструмент MCP get_server_info доступен только для чтения и не требует плагина или connection_id. Singleton, связанный со слушателем и реестром подключений бэкенда, возвращает UUID экземпляра, идентификатор процесса, версию продукта, время запуска процесса в UTC, число активных подключений и фактический адрес Bridge. Вызовы ждут запуска приложения и читают адрес, привязанный Kestrel, поэтому запасной порт можно узнать без командной оболочки и журналов запуска. Ответ фиксированной структуры не содержит переменных окружения, учётных данных или посторонней информации о компьютере; см. справочник инструментов.
Протокол Bridge
- Один map MessagePack на бинарный WebSocket-кадр.
- Подпротокол
figma-mcp-bridge.v2. - Поля конверта:
type,protocol_version,sent_at, а при необходимости —connection_id,request_id,method,payloadиerror. - Канонические UUID в нижнем регистре и временные метки UTC в формате ISO 8601.
- Ограничение сообщения Bridge — 16 МиБ, данных base64 — 12 МиБ.
- Список разрешённых операций и структурированные данные; выполнение JavaScript и произвольное отражение свойств запрещены.
Запросы для одного подключения выполняются последовательно с тайм-аутом 30 секунд. Изменения могут использовать dry_run и idempotency_key; плагин хранит результаты в рамках текущего запуска, чтобы повторный ключ не выполнял запись ещё раз.
Состояние и границы безопасности
Реестр подключений и ожидающие запросы находятся только в памяти компаньона. После перезапуска процесса плагин должен подключиться повторно.
Bridge доступен только через loopback-интерфейс. Перед принятием подключения проверяются значения Host, Origin и подпротокол WebSocket. Плагин хранит только локальный порт Bridge и не передаёт токен доступа в URL WebSocket или конвертах Bridge.