# Figma Local MCP

Локальный MCP для чтения, редактирования и создания макетов с нуля через Figma Plugin API. Переносимый пакет с открытыми исходниками runtime и плагина, профилем Gravity UI по умолчанию и дополнительным shadcn/ui, правилами проекта и сценарием style guide → компоненты → экраны.

```text
MCP-клиент → stdio → Node.js MCP → WebSocket 127.0.0.1:3055
                                        ↓
                            плагин в Figma Desktop
                                        ↓
                          Plugin API открытого файла
```

Сервер и плагин не вызывают Figma REST API, официальный Figma MCP или Figma AI. Токен Figma не нужен. Поэтому эти команды не создают запросов, учитываемых в квотах REST API и официального MCP. Это вывод из архитектуры, а не обещание неограниченного доступа к любым возможностям Figma. Синхронизация самого редактора с Figma продолжает работать обычным образом; лимиты AI-клиента также сохраняются.

Основания: [лимиты официального MCP](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/), [лимиты REST API](https://developers.figma.com/docs/rest-api/rate-limits/), [доступ к документу из плагина](https://developers.figma.com/docs/plugins/accessing-document/).

## Передача и установка

Скачайте/передайте ZIP из `dist/`. Он содержит собранный сервер, Figma-плагин, скилл и исходники. Получателю нужны Node.js 22+ и Figma Desktop; устанавливать npm-зависимости не требуется.

### Установка из GitHub

Проект можно установить непосредственно из исходников. Нужны Node.js 22+, npm и Python 3:

```bash
git clone https://github.com/lostpunk/figma-local-mcp.git
cd figma-local-mcp
npm ci
npm run release
node scripts/setup.mjs --codex
```

После setup импортируйте `generated/figma-plugin/manifest.json` в Figma Desktop и запустите плагин. Локальные ключи подключения создаются только на компьютере пользователя и не хранятся в GitHub.

Из распакованной папки выполните:

```bash
node scripts/setup.mjs --codex
```

Затем импортируйте `generated/figma-plugin/manifest.json` в Figma Desktop и запустите плагин. Он подключается автоматически, без ввода кода, и восстанавливает связь после перезапуска MCP. Держите его окно открытым. Установщик создаёт отдельный локальный ключ для каждого получателя; передавайте только ZIP из `dist/`.

- [INSTALL.md](INSTALL.md) — пошаговая инструкция для получателя и других MCP-клиентов.
- [CUSTOMIZE.md](CUSTOMIZE.md) — правила проекта, UI-библиотеки и доработка скилла.
- [CONTRIBUTING.md](CONTRIBUTING.md) — пересборка и распространение ZIP.
- [SKILL.md](skills/figma-local-design/SKILL.md) — инструкции для агента.

Сам скилл не запускает MCP: setup регистрирует сервер и устанавливает скилл отдельно. Без Codex CLI команда `node scripts/setup.mjs` создаст конфигурации с корректными путями для вашего компьютера.

## Несколько задач Codex

MCP-клиенты одной установки подключаются к общему локальному мосту на порту 3055. Можно открыть несколько задач: закрытие одной не отключает Figma для остальных. В `get_connection` поле `transport: "shared"` обозначает этот режим, а `clientCount` показывает число MCP-подключений. Все они работают с одним открытым файлом Figma; одновременно выполняется только одна операция. При занятости дождитесь результата и заново прочитайте состояние.

Мост проверяет ключ установки и совпадение версии, не завершает чужие процессы и не передаёт ключ неизвестной службе на занятом порту. Через три секунды после отключения последнего MCP-клиента он завершается. После обновления закройте все старые MCP-клиенты, подождите несколько секунд и перезапустите Codex и Figma Local MCP Auto. Старый мост версии до 0.7.15 не поддерживает совместное подключение.

## Создание с нуля: от style guide до экрана

Начните с открытого пустого файла Figma Design и подключённого плагина. Один вызов `create_style_guide` с аргументами `{"name":"My Product"}` создаёт:

- фрейм с редактируемыми образцами: на новой странице `My Product — Style guide`, если бюджет позволяет, либо на существующей странице;
- коллекцию переменных: 10 цветов, 8 отступов и 6 радиусов;
- 5 текстовых стилей на Inter: H1, H2, Body, Label и Caption;
- привязки цветовых образцов к COLOR-переменным, промежутков и радиусов к FLOAT-переменным, текстовых образцов к TextStyle.

Это стартовый набор. Агент может передать свои массивы `colors`, `typography`, `spacing`, `radii` под конкретный продукт; каждый переданный массив заменяет соответствующий набор по умолчанию. Создание использует один режим переменных и не требует дополнительных режимов темы.

Команда возвращает `pageId`, `frameId`, `collectionId`, `modeId` и ID каждого токена/стиля. Затем:

1. Прочитайте `get_document.capabilities`: число страниц, источник сведений о тарифе и доступный бюджет. `create_page` возвращает существующую страницу с таким именем либо создаёт новую в пределах бюджета.
2. `create_scene` создаёт до 100 узлов за вызов. Временные `ref` и `parentRef` позволяют описать вложенные фреймы, текст и компоненты без промежуточных запросов.
3. В `props` передавайте `fillVariableId`, `strokeVariableId`, `textStyleId` и `variableBindings`, используя ID из style guide.
4. `create_instance` размещает экземпляры созданного компонента на экранах.
5. `set_variable` меняет цвет или числовой токен; связанные свойства слоёв обновляются средствами Figma.
6. `set_selection` открывает нужную страницу и фокусирует узлы, `export_node` возвращает изображение для проверки.

Пример запроса к агенту:

> Используй только figma_local. В открытом пустом файле создай style guide для сервиса управления проектами: синий основной цвет, светлая тема, Inter, шкала отступов 4/8/12/16/24/32/48. Затем создай страницу Components с компонентом кнопки и страницу Screens с экраном входа. Привяжи цвета, отступы и текст к переменным и стилям. Используй экземпляр кнопки на экране и покажи PNG результата.

Подробный пример аргументов — [examples/from-scratch.md](examples/from-scratch.md).

Повторное создание guide с тем же именем отклоняется, чтобы не размножать стили. Существующий набор можно прочитать через `get_design_system` и изменить его COLOR/FLOAT значения через `set_variable`. Эта версия не редактирует определения текстовых стилей, не публикует библиотеки.

Образцы связаны с токенами, но их текстовые подписи с HEX/px отражают момент создания. После изменения токенов актуальные значения читайте через `get_design_system`; подписи при необходимости меняйте через `update_node`. Текущая страница после создания guide не переключается автоматически.

Создание ресурсов основано на [Plugin API переменных](https://developers.figma.com/docs/plugins/working-with-variables/) и [локальных текстовых стилях](https://developers.figma.com/docs/plugins/api/TextStyle/). Ограничения возможностей редактора, прав и тарифного плана сохраняются. Ни один новый инструмент не вызывает REST API или официальный MCP.

## Инструменты

| Инструмент | Действие |
| --- | --- |
| `get_connection` | Статус подключения и согласованность версий; установленный плагин подключается автоматически, ключ не выдаётся |
| get_diagnostics | Локальные ошибки, requestId, PID, идентификатор запуска и длительность операций |
| import_image / import_svg | Фотографии и редактируемая векторная графика |
| create_component_set / set_instance_properties | Варианты компонентов и свойства экземпляров |
| set_prototype_link / set_prototype_start | Переходы, интерактивные состояния и точки старта |
| move_component | Перенос существующего компонента или набора с сохранением связей экземпляров |
| `get_document` | Имя файла, список страниц, текущая страница |
| `get_selection` | Выделенные узлы и ограниченное дерево потомков |
| `get_node` | Узел по ID: геометрия, текст, заливки, эффекты, auto layout |
| `get_design_context` | Единый контекст экрана: структура, оформление, текст, компоненты, значения токенов, ресурсы и PNG-превью; CSS по запросу |
| `get_text_runs` | Форматированные фрагменты текста: шрифты, заливки, ссылки и привязки токенов; постраничное чтение |
| `get_component_details` | Связь экземпляра с главным компонентом, ключи, варианты и определения свойств набора |
| `get_bound_variables` | Привязанные переменные и значения для конкретного слоя с учётом режимов и aliases |
| `find_nodes` | Поиск по имени или тексту на одной странице, с пагинацией |
| `create_node` | Создание FRAME, RECTANGLE, ELLIPSE, TEXT, COMPONENT |
| `update_node` | Изменение поддерживаемых свойств узла |
| `preview_audit_fixes` | Предложения исправлений выбранных выходов за границы, с объяснением пропущенных случаев |
| `list_operations` | Поиск прежних ID и статусов в ограниченной локальной истории |
| `preview_changes` | Различия «до → после» для свойств существующих слоёв, без изменения макета |
| `apply_changes` | Применение выбранных изменений из плана с проверкой устаревшего состояния |
| `update_page` | Имя страницы и единый цвет холста |
| `reparent_nodes` | Перенос слоёв в контейнер с сохранением координат и опциональным индексом слоя |
| `reorder_nodes` | Порядок прямых потомков: индекс 0 — самый нижний слой |
| `set_image_fill` | Image fill из base64 PNG/JPEG/GIF/WebP; неподдерживаемое кодирование нормализуется локально |
| `set_image_fill_from_path` | Image fill из абсолютного локального пути с проверкой сигнатуры и размера файла |
| `delete_node` | Удаление узла и его потомков |
| `set_selection` | Выделение узлов одной страницы и фокусировка |
| `export_node` | PNG в виде MCP image или SVG в виде текста |
| `export_assets` | До 20 PNG/JPG/SVG/PDF-экспортов или исходных изображений в новую локальную папку; пути, хеши и журнал результатов |
| `create_style_guide` | Страница с образцами, коллекция переменных и текстовые стили |
| `get_design_system` | Локальные коллекции, переменные и текстовые стили; фильтр `prefix` |
| `create_page` | Новая страница в открытом файле |
| `create_scene` | Пакетное создание до 100 узлов по `ref` / `parentRef` |
| `create_instance` | Экземпляр локального компонента |
| `import_web_snapshot` | Предпросмотр и перенос снимка веб-страницы в редактируемые слои: текст, PNG и простые flex-контейнеры |
| `get_library_variables` | Коллекции и переменные из включённых библиотек, с пагинацией |
| `import_library_asset` | Импорт компонента, набора вариантов или переменной по проверенному опубликованному ключу |
| `get_variable_modes` | Режимы коллекции и явный/эффективный режим слоя |
| `create_variable_mode` | Предпросмотр и создание локального режима копированием значений и aliases |
| `set_variable_mode` | Предпросмотр и переключение режима слоя или возврат к наследованию |
| `set_variable` | Изменение COLOR/FLOAT значения в default mode или заданном `modeId` |

Для `get_node` и `get_selection`: `depth` от 0 до 6, `maxNodes` от 1 до 1000. По умолчанию 2 и 200. `childrenTruncated` показывает пропущенных потомков; `selectionTruncated` — пропущенные корни выделения. Текст длиннее 10 000 символов сокращается с `charactersTruncated` и полным `characterCount`. Значение `figma.mixed` возвращается как `{"mixed":true}`.

`find_nodes` возвращает `nextOffset` для следующего вызова с прежними фильтрами. `complete: false` означает, что нужно продолжить, даже если `nodes` пуст. `maxVisited` ограничивает новые просмотренные узлы после `offset`; сдвиг к offset тоже требует обхода. Изменения файла между страницами выдачи могут сдвигать результаты.

`get_node` и `get_selection` ограничивают ответ по числу узлов и размеру UTF-8: по умолчанию 1 MiB, параметр `maxResponseBytes` — от 4096 байт до 4 MiB. `fields` выбирает свойства; `fields: []` возвращает только структуру и метаданные. Продолжайте корневой список через `childOffset` / `selectionOffset` из `nextChildOffset` / `nextSelectionOffset`; вложенные обрезанные узлы читайте отдельно по ID. Для дочерних узлов нужен `depth >= 1`. `omittedProperties` перечисляет свойства, не поместившиеся в бюджет; запросите нужное свойство отдельно. Если оно само превышает бюджет, ответ останется явно неполным. После изменений структуры или выделения начните обход заново.

`get_design_system` выдаёт каждый список отдельно с `pagination`: `collections`, `variables`, `textStyles`. Для продолжения передайте соответствующие `nextOffset` в `offsets` вместе с `revision`. Изменение ресурсов или фильтров требует начать обход заново. `prefix` фильтрует имена коллекций и текстовых стилей; `variableNamePrefix` — имена токенов; `collectionId` ограничивает коллекции и переменные, но не текстовые стили.

Для подробного чтения используйте `get_text_runs`, `get_component_details` и `get_bound_variables`; они не меняют макет и не утяжеляют обычное чтение дерева. Текст продолжается через `nextStart` в единицах UTF-16, переменные — через `nextOffset`. `get_bound_variables` не обходит потомков и смешанные текстовые фрагменты: их токены передаются отдельно через `variableIds` из результата `get_text_runs`. Неполные ответы и недоступные ресурсы обозначены явно. Все три команды поддерживают `maxResponseBytes`; при `blocked: true` измените диапазон/поля/бюджет, а не повторяйте запрос без изменений. [Подробности для переноса в код](skills/figma-local-design/references/design-to-code.md).

### Свойства для создания и редактирования

Для выборочных изменений доступен сценарий `preview_changes` → `apply_changes`: план хранится пять минут, применяется один раз и проверяет свойства выбранных слоёв и контекст их родителей перед записью. Поддерживаются простая геометрия и оформление прямоугольников/эллипсов; для текста — метаданные и безопасное увеличение фиксированной высоты; для фиксированных горизонтальных/вертикальных Auto Layout фреймов — отступы, интервалы и размеры с проверкой положения детей. Через `preview_design_fixes` можно отдельно подготовить однозначные привязки к переменным цвета и текстовым стилям. Стили, привязки к переменным, Auto Layout и компоненты имеют дополнительные ограничения. Это предпросмотр свойств, а не отрисовка будущего экрана. [Полный порядок работы и ограничения](skills/figma-local-design/references/preview-changes.md).

- Геометрия: `x`, `y`, `width`, `height`, `rotation`, `cornerRadius`.
- Вид: `name`, `visible`, `locked`, `opacity`, `fill`, `stroke`, `strokeWeight`.
- Текст: `characters`, `fontName: {family, style}`, `fontSize`, `textAlignHorizontal`.
- Дополнительная типографика: `textAutoResize`, `lineHeight: {unit: "PIXELS" | "PERCENT", value}`.
- Стили и токены: `textStyleId`, `fillVariableId`, `strokeVariableId`, `variableBindings`.
- Auto layout: `layoutMode`, `itemSpacing`, `paddingTop/Bottom/Left/Right`, `primaryAxisAlignItems`, `counterAxisAlignItems`, `primaryAxisSizingMode`, `counterAxisSizingMode`, `clipsContent`.

`fill` и `stroke` принимают `#RRGGBB` или `null` для очистки. Они заменяют весь список заливок/обводок на один сплошной цвет. Свойства текста применяются ко всему текстовому узлу. Перед текстовыми изменениями загружаются шрифты. Свойства, недоступные для данного типа узла, приводят к ошибке. Ограничения экземпляров компонентов проверяет Figma.

`textStyleId` нельзя совмещать в одном вызове с `fontName`, `fontSize` или `lineHeight`; `fillVariableId` — с `fill`; `strokeVariableId` — со `stroke`. Выберите стиль/токен или явное значение. `variableBindings` — объект из полей `width`, `height`, `itemSpacing`, `paddingTop/Bottom/Left/Right`, `topLeftRadius`, `topRightRadius`, `bottomLeftRadius`, `bottomRightRadius`; значения — ID FLOAT-переменных либо `null` для снятия привязки. Привязки применяются после обычных свойств.

Пример аргументов `create_node`:

```json
{
  "type": "FRAME",
  "props": {
    "name": "Card",
    "width": 320,
    "height": 180,
    "fill": "#FFFFFF",
    "cornerRadius": 16,
    "layoutMode": "VERTICAL",
    "itemSpacing": 12,
    "paddingTop": 24,
    "paddingLeft": 24
  }
}
```

Вернувшийся `id` можно передать как `parentId` при создании дочернего текста. `parentId` поддерживает PAGE, FRAME, COMPONENT и SECTION.

## Перенос макета в код

Скажите: «Используй плагин Фигма, чтобы изучить выбранный экран и сверстать его в этом проекте». Скилл читает структуру слоёв, геометрию, доступные токены и состояния, сопоставляет их с PNG-превью и существующими компонентами приложения. Реализация учитывает стек проекта; исходный файл Figma остаётся без изменений, если вы не попросили редактировать его.

Это работа агента по данным локального плагина, а не универсальный экспорт готового приложения одной командой. Неизвестная адаптивность, отсутствующие шрифты, неподтверждённые взаимодействия и недоступные ресурсы указываются отдельно. После реализации выполняются проверки проекта и, когда доступен браузерный просмотр, визуальное сравнение. Можно отдельно попросить только изучить макет и подготовить план. [Порядок работы и ограничения](skills/figma-local-design/references/design-to-code.md).

`get_design_context` объединяет чтение выбранного фрейма/слоя и PNG-превью. По умолчанию: глубина 2, до 50 узлов, бюджет 1 MiB; CSS включается отдельно. Ответ сохраняет порядок и родительские связи, показывает пропуски и продолжение через `coverage.nextOffset`; большие детали дочитываются специализированными инструментами. Макет не изменяется, файлы не сохраняются, фреймворк не выбирается. [Состав контекста и работа с ограничениями](skills/figma-local-design/references/design-context.md).

## Ограничения

Для выгрузки файлов через `export_assets` выберите каталог ресурсов проекта с `scripts/asset-access.mjs --allow-export /absolute/project/assets`. Это отдельное разрешение от импорта. Инструмент сохраняет до 20 ресурсов в новую папку и не перезаписывает существующие файлы; ограничения — 8 MiB на файл, 64 MiB на пакет, до 4096 px на сторону для растрового рендера. Исходные изображения не уменьшаются. Частичные результаты и причины ошибок перечисляются в журнале выгрузки. [Порядок экспорта и восстановления](skills/figma-local-design/references/export-assets.md).

- Один подключённый файл на локальный мост. Несколько MCP-клиентов одной установки используют общий мост на порту 3055; операции выполняются последовательно. Другой плагин не вытесняет уже подключённую сессию. Для отдельного экземпляра нужно согласованно изменить `FIGMA_BRIDGE_PORT`, WebSocket URL в `plugin/ui/connection.js` с последующей сборкой и `devAllowedDomains` в manifest.
- Плагин работает в Figma Design. Он не открывает произвольные файлы по ссылке, не работает в фоне с закрытым редактором и не обходит права доступа или политику организации по плагинам.
- Нет Figma AI, Make, Code Connect, комментариев, REST-поиска файлов, публикации библиотек, градиентных заливок или произвольного исполнения JavaScript. Создание нового файла Figma по-прежнему выполняется пользователем; инструменты создают страницы внутри открытого файла.
- Image fill принимает PNG, JPEG, GIF и WebP. Локальный путь должен быть абсолютным, указывать на обычный файл до 8 MiB и проходить проверку сигнатуры; байты не уходят в сторонние сервисы. При необходимости WebP и нестандартные JPEG/PNG декодируются UI плагина и сохраняются в файле как PNG.
- Для style guide создаются только локальные COLOR/FLOAT переменные и TextStyle, без алиасов и дополнительных режимов. Ограничения режима или типа переменной в `set_variable` проверяются до записи.
- Изменения не являются транзакциями. При ошибке `update_node` часть свойств могла измениться; ошибка сообщает об этом. После успешных изменений вызывается `commitUndo`; отмена выполняется в Figma. Неудачно созданный узел удаляется.
- При ошибке `create_style_guide` или `create_scene` выполняется очистка только ресурсов текущего вызова. Если очистка не удалась, ошибка перечисляет оставшиеся ресурсы. Таймаут транспорта не отменяет уже запущенную сборку: перед повтором проверьте файл.
- Таймаут команды bridge — 120 секунд; сгенерированная конфигурация Codex резервирует для неё 150 секунд. Если другой MCP-клиент или внешний агент прекращает ожидание раньше, bridge не разрывает подключение: `get_connection.operation` покажет `timed_out_waiting_result` до позднего ответа плагина. Результат отправленного изменения всё равно может быть неизвестен, поэтому перед повтором проверьте файл; остановка соединения не отменяет уже запущенный Plugin API вызов.
- PNG ограничен до 4096 пикселей по большей стороне и 8 MiB; масштаб при необходимости уменьшается и возвращается в метаданных. SVG ограничен по длине 4 Mi символов.

## Локальное соединение и данные

Bridge слушает только `127.0.0.1`. Установщик сохраняет случайный локальный ключ длиной 32 байта в `generated/pairing-key.json` и в персональной копии UI. На macOS/Linux эти файлы доступны только владельцу (0600). Сервер проверяет ключ при каждом соединении. Без setup сервер попросит подготовить автоматический плагин. Ключ никогда не возвращается в ответах MCP. Плагин не делает запросов к внешним доменам: в manifest разрешён только development WebSocket. Команды идут по списку известных операций, без `eval`, команд оболочки или передачи cookies Figma.

Содержимое макетов, прочитанное инструментами, возвращается MCP-клиенту и может попасть в контекст его AI-провайдера. Локальный bridge не означает локальную обработку моделью. Ключ подключения даёт доступ к сессии открытого файла. Каталог `generated/` содержит персональный ключ и не включается в ZIP; не передавайте этот каталог другим людям.

## Проверки

```bash
npm test
```

Автоматические проверки включают TypeScript-сборку и тесты: операции с узлами, style guide, переменные, импорт локальной картинки, порядок слоёв, ошибки, таймауты и защита подключения; запуск bundle без node_modules; генерация переносимых путей; установка/резервное копирование скилла; регистрация MCP с имитацией Codex CLI. Интеграционные тесты запускают настоящий MCP-клиент через stdio, настоящий WebSocket и собранный код плагина с имитацией Figma API; проходят путь от style guide до экземпляра компонента и изменения токена. Настройки реального Codex в тестах не изменяются.

Чтение, создание макета, компонентов, экземпляров и PNG-экспорт проверены в настоящем Figma Desktop. Автоподключение отдельно проверяется тестами UI и локального транспорта; эти тесты не заменяют проверку новой установки в редакторе.

Основные файлы: `src/server.mjs` — инструменты, `src/design-schema.mjs` — схемы guide/scene, `src/bridge.mjs` — локальное соединение, `plugin/code.ts` — изменение узлов, `plugin/node-reader.ts` — чтение, поиск и экспорт, `plugin/design-system.ts` — style guide, токены и сборка сцен. Исходники окна находятся в `plugin/ui/`, HTML и стили — в `plugin/ui.template.html`; сборка создаёт один автономный `plugin/ui.html`. Общие лимиты ответов заданы в `src/response-limits.json`, подсчёт UTF-8 — в `plugin/response-size.ts`. После изменения исходников выполните `npm run build` и перезапустите плагин. Для появления новых инструментов перезапустите MCP-клиент. После setup плагин восстанавливает подключение автоматически; сборка обновляет его персональную копию в `generated/figma-plugin/`.

## Тариф файла и ограничения страниц

Публичный Plugin API не сообщает тариф команды. Поэтому `get_document.capabilities` честно возвращает неизвестный тариф, подтверждённый пользователем тариф или ограничение, ранее полученное в ошибке Figma. `figma.payments` относится к оплате плагина и здесь не используется.

В окне Figma Local MCP Auto можно выбрать тариф команды текущего файла; настройка хранится отдельно в документе. При неизвестном тарифе действует предел безопасности в три страницы. При Starter — три страницы. Для подтверждённого Professional/Education/Organization/Enterprise искусственный предел снимается, но ограничения самого редактора остаются.

При исчерпанном бюджете `create_page` останавливается **до вызова Figma API**, а `create_style_guide` размещает фрейм справа от существующего контента. Можно явно указать `pageId`. Никаких пробных страниц для определения тарифа не создаётся. Повторный `create_page` с тем же именем возвращает существующую страницу.

См. [правила скилла для лимитов](skills/figma-local-design/references/file-limits.md) и [лимиты страниц Figma](https://help.figma.com/hc/en-us/articles/360038511293-Create-and-manage-pages).

## Установка одним скиллом

Передайте `dist/figma-local-design-skill-0.7.35.zip`. Получателю достаточно установить папку `figma-local-design` как скилл и написать агенту:

> Используй $figma-local-design и установи всё необходимое для работы с Figma.

Скилл содержит установщик и проверяемый SHA256 пакет MCP. Агент развернёт его локально, зарегистрирует MCP и откроет manifest автоматического плагина. Нужны Node.js 22+ и Codex CLI для автоматической регистрации; npm и Python получателю не нужны. В Figma останется один раз импортировать manifest через меню Plugins → Development и запустить Figma Local MCP Auto.

По умолчанию отдельное скачивание не нужно: проверяемые исходники runtime и плагина вложены в скилл. Установщик намеренно не скачивает и не запускает удалённый исполняемый код; для распространения используйте проверяемый ZIP скилла или GitHub-репозиторий.

## Изменения 0.7.5

- Проверка готовности и версий MCP, плагина и скилла перед изменениями.
- ID операций и `get_operation`: восстановление результата без повторного создания объектов; старые ID после перезапуска или вытеснения отклоняются.
- Подтверждение доставки и восстановление результатов при переподключении того же окна плагина. Кэш хранится только в памяти и ограничен по размеру.
- В плагине видны версии, время выполнения, подсказка восстановления и кнопка копирования отчёта без содержимого макета.
- Откат базовых свойств простых фигур при ошибке обновления; сложные изменения по-прежнему требуют проверки результата.

## Изменения 0.7.4

Добавлены SVG, варианты компонентов, прототипные переходы и перенос компонентов с сохранением экземпляров. Доступны постоянный журнал ошибок и журнал в окне плагина; события содержат requestId, PID и идентификатор запуска. Исправлены чтение вариантов, переход на собственный экран и двойные записи ошибок. Сохранены операции со слоями, нормализация изображений и ожидание позднего результата долгих команд. Всего 29 MCP-инструментов.

Установка и работа с настоящей Figma проверены на macOS. Полный сценарий на Windows/Linux не проверен; автоматическая регистрация через codex.cmd на Windows требует отдельной проверки. Для локального development-плагина нужна Figma Desktop.

## Исправления 0.7.6

- Привязки цветов и числовых свойств сначала ищут переменные в текущем файле. Сбой поиска по ID больше не блокирует доступные локальные переменные.
- Изменение локального токена использует локальные переменные и коллекции. Список обновляется для каждой команды.
- Ошибки подготовки переменных и шрифтов до записи явно сообщают, что свойства не изменены, без лишнего шага Undo. Ошибки после начала записи по-прежнему требуют проверки узла.

## Изменения 0.7.7

- Локальные привязки компонентов Figma к коду через `codeComponents` в конфигурации проекта: точные ключи, преобразование вариантов и свойств, явные пропуски. Переносимый CLI проверяет наличие исходников; экспорты и типы проверяются по коду проекта. Это независимые локальные правила, без чтения или публикации официального Code Connect.
- Проверка `.figma-design.json` и выбранных файлов правил через переносимый `scripts/project-rules.mjs` внутри скилла: библиотека, палитра, типографика, сетка, именование и состояния компонентов.
- `sync_style_guide`: предпросмотр и применение изменений в существующей коллекции с сохранением ID переменных и стилей. Повтор одинаковых значений не создаёт дубликаты или шаг Undo.
- Пропущенные токены и дополнительные режимы сохраняются. При ошибке предпринимается откат; макеты и коллекции не пересоздаются.
- Инструмент не переписывает старые текстовые подписи образцов и не выполняет автоматический аудит экранов.

## Изменения 0.7.9

- При первой настройке пользователь выбирает дизайн-систему и правила своего проекта; выбор больше не подставляется молча.
- Терминальный мастер или вопросы через агента: текущий стиль Figma, shadcn/ui, Material Design, своя система, либо отложенный выбор.
- Тема, плотность, устройства, шрифт, цвет бренда и правила сохраняются только в `.figma-design.json` выбранного проекта.
- Повторная установка сохраняет существующий файл. Начать настройку другого проекта можно отдельно через `scripts/onboarding.mjs` внутри скилла, без переустановки MCP.

## Изменения 0.7.11

- MCP и плагин получают версию из `package.json`: устранена ошибочная блокировка редактирования после обновления.
- Тесты проверяют согласованность версии пакета с ответом сервера и сообщением собранного плагина.

## Изменения 0.7.10

- Общий профиль Gravity UI с публичными источниками и приветствием при первой настройке.
- Выбор другой системы, сохранение текущего стиля и отложенная настройка.
- Существующие правила проекта сохраняют приоритет; Figma-кит автоматически не импортируется.

## Изменения 0.7.12

- Новый `audit_design` проверяет видимое дерево страницы или фрейма без изменений макета: границы, признаки переполнения текста, недоступные шрифты и настройки усечения.
- По переданным правилам проекта проверяются отступы auto layout и значения состояний компонентов. Имена локальных текстовых стилей проверяются на дубли.
- Отчёт содержит ID объектов, признаки неполного обхода и ограничения проверки. Замечания требуют визуальной оценки; автоматического исправления нет.
- Подробности: [проверка качества](skills/figma-local-design/references/quality-checks.md). Всего 32 MCP-инструмента.

## Изменения 0.7.13

- Импорт локальных PNG/JPEG/GIF/WebP и SVG читает только явно выбранные каталоги. По умолчанию доступ к путям закрыт; `scripts/asset-access.mjs` добавляет и отзывает каталоги без перезапуска MCP.
- Общая проверка реального пути, символических ссылок, типа файла и ограничение чтения заменяют отдельный путь загрузки изображения.
- SVG проверяется на неподдерживаемые атрибуты/CSS, отсутствующие цели, циклы и чрезмерное разрастание ссылок.
- Ключ сопряжения больше не возвращается клиенту; для запуска нужен подготовленный автоматический плагин.
- [Настройка доступа к ресурсам](skills/figma-local-design/references/asset-access.md).

### Улучшения проверки и предпросмотра в 0.7.21

- `preview_audit_fixes` предлагает рост фиксированной текстовой рамки после проверки родителя и соседей, а также прежние перемещения простых фигур.
- `preview_changes` рассчитывает позиции детей при изменении отступов, промежутков и размеров существующего фиксированного Auto Layout фрейма. Поддерживаются горизонтальные/вертикальные стеки без wrap/fill/absolute; сложные случаи возвращают причину ограничения.
- `audit_design.rules.designSystem` проверяет явно выбранные переменные цветов, текстовые стили и компоненты. `ignoreNodeIds` задаёт исключения для конкретных слоёв. Эти правила можно сохранить в `.figma-design.json` → `audit.designSystem`.
- `preview_design_fixes` создаёт план привязок при единственном точном совпадении текущего вида и указанного токена/стиля. Назначение токена выбирает пользователь/агент в рамках проекта; неоднозначные совпадения и замены компонентов пропускаются.
- Окно плагина показывает итог проверки, причины пропуска, количество изменённых слоёв и кнопку перехода к слою. Подтверждение исправления требует повторного аудита и визуальной проверки.

Предпросмотр не создаёт временных страниц и не рендерит альтернативный макет. Связанные изменения одного Auto Layout фрейма выбираются вместе. Изменения компонентов и экземпляров как целей предпросмотра, гибкие размеры и полная автоматическая перевёрстка пока не поддерживаются. Проверки вычислений с имитацией API не заменяют проверку новой сборки в Figma Desktop.

Состав runtime, скилла и исходного архива описан в `src/package-layout.json`: секции `skill` и `source` добавляют файлы к `runtime`. Этот список используют сборка, упаковщики и локальная установка. Проверки обязательных файлов, приватных данных и контрольных сумм выполняются отдельно. Тесты входят в архив исходников, но не в устанавливаемый скилл.

Библиотеки и темы используют Figma Plugin API: доступ к библиотекам и ограничения тарифа сохраняются. Библиотеки включаются вручную в Figma. Импорт не создаёт экземпляр автоматически; изменение режима начинается с предпросмотра и проверяет его актуальность. Инструкции: [libraries-themes.md](skills/figma-local-design/references/libraries-themes.md).

Для переноса сайта агент использует доступный браузер и включённый сборщик DOM, затем передаёт локальный JSON в `import_web_snapshot`. Плагин не запускает HTML/JS сайта и не скачивает URL. Это приближённый снимок выбранного размера, с явными пропусками и последующим сравнением скриншотов. Инструкции: [web-import.md](skills/figma-local-design/references/web-import.md).