Русский
Покрытие Figma Plugin API
Область и первоисточники
Документ сопоставляет публичный Figma Plugin API с возможностями MCP для локальной архитектуры компаньона. Использованы официальные материалы Figma:
- Обзор API
- Глобальный объект
figma - Глобальные объекты
- Типы узлов
- Общие свойства узлов
- Типы данных
- Манифест плагина
- Ошибки API
Также изучены связанные с глобальным объектом публичные API: UI, utilities, constants, Motion, codegen, timer, viewport, client storage, parameters, text review, payments, variables, team library, annotations и Buzz; все типы узлов и группы свойств из индекса общих свойств.
Официальный npm-пакет @figma/plugin-typings служит машинно-читаемым дополнением к справочнику. Для сверки семейств интерфейсов использована версия 1.131.0, разрешённая текущим репозиторием.
Это каталог семейств API, а не рекомендация создавать MCP-инструмент для каждого свойства TypeScript. В Plugin API сотни свойств узлов. Небольшой набор составных типизированных инструментов с ограничениями обеспечивает практическое покрытие и не перегружает список MCP-инструментов.
Статус реализации
Часть каталога, относящаяся к Figma Design, реализована коннектором, описанным в этой документации. Полный список зарегистрированных инструментов и правила входных данных приведены в справочнике инструментов MCP.
Реализация намеренно исключает инструменты для отдельных редакторов из раздела 11, API с обработчиками запуска и управления продуктом из раздела 12, приватные/партнёрские API, произвольные сетевые запросы и выполнение JavaScript. Чтение измерений доступно в Design; изменение измерений возвращает unsupported_in_editor, так как Figma разрешает такую запись только в Dev Mode.
Принципы проектирования инструментов
Для каждого инструмента документа обязателен connection_id. Кроме того:
- Используйте стабильные составные инструменты. Представляйте чтение и запись свойств типизированными проекциями и наборами изменений вместо сотен специализированных инструментов.
- Ограничивайте каждый результат чтения. Используйте явный набор полей, глубину обхода, лимиты результатов и курсоры продолжения. Большие экспорты и медиа возвращайте как MCP-ресурсы или по частям, а не одним JSON.
- Полностью инициализируйте отслеживание изменений. Один раз вызовите
loadAllPagesAsync()перед регистрациейdocumentchange: Figma требует этого в dynamic-page. Bridge должен ждать завершения инициализации, чтобы учитывать ручные изменения и изменения через коннектор. - Последовательно выполняйте записи внутри подключения. Сохраняйте последовательность запросов одного плагина, разрешая чтение по другим подключениям параллельно.
- Делайте записи проверяемыми. Изменяющие инструменты должны поддерживать
dry_run,idempotency_keyи ограниченную пакетную операцию, а также возвращать ID созданных, изменённых и удалённых узлов и предупреждения. - Сохраняйте семантику Figma. Не сериализуйте необработанные proxy-объекты Figma. Преобразуйте заливки, эффекты, векторы, переменные, стили, реакции и другие значения в версионные DTO.
- Объявляйте возможности среды выполнения. Доступный API зависит от типа редактора, режима, разрешений манифеста, возможностей, статуса публикации плагина, а также публичности и бета-статуса API.
- Точно аннотируйте MCP-инструменты. Для инструментов только чтения задавайте
readOnlyHint, а для записи — подходящийdestructiveHintилиidempotentHint.
Каталог возможностей
1. Поиск подключений, возможности и контекст документа
| Инструмент | Назначение |
|---|---|
get_figma_capabilities | Тип и режим редактора, версия публичного API, разрешения/возможности манифеста, типы узлов, дополнительные API, бета-функции и возможность записи |
get_figma_document | Ограниченный набор полей документа, сводки страниц, цветовой профиль, узел миниатюры, текущая страница и безопасный для пользователя контекст редактора |
list_figma_pages | Сводки страниц и разделителей с пагинацией и сведениями о загрузке |
load_figma_page | Явная загрузка страницы по ID для последующей работы в dynamic-page |
get_figma_selection | Ограниченное представление текущего выделения и выбранного диапазона текста |
set_figma_selection | Выделение заданных ID узлов и, при необходимости, переход к ним/масштабирование |
set_figma_current_page | Переключение на выбранную страницу через асинхронный API dynamic-page |
get_figma_document_changes | Чтение журнала изменений по курсору: documentchange, выбор, страницы и стили |
Это семейство охватывает документ, корневой и текущий контекст, загрузку страниц, выделение, режим редактора, события узлов/стилей и публичные поля текущего пользователя/активных пользователей при наличии разрешений и политики.
2. Обнаружение дерева и чтение проекций узлов
| Инструмент | Назначение |
|---|---|
get_figma_nodes | Чтение узлов по ID с явным набором полей и ограниченным обходом потомков |
query_figma_nodes | Поиск на загруженной странице или в поддереве по типам, имени, видимости, ключу plugin data, компоненту/экземпляру и другим критериям |
get_figma_node_css | Результат getCSSAsync() для заданных узлов |
get_figma_node_geometry | Трансформации, границы, заливки/обводки, векторные пути и сеть, дуги/точки, углы, layout grid, ограничения и auto/grid layout |
get_figma_text | Текст и запрошенные свойства диапазонов/стилизованных сегментов с пагинацией |
get_figma_components | Компоненты, component sets, экземпляры, слоты, варианты, переопределения и свойства компонентов |
get_figma_prototype | Реакции, flow, overlay, переходы, точки подключения и параметры прототипа |
get_figma_plugin_data | Приватные/общие данные этого плагина и данные повторного запуска для заданных узлов/стилей |
get_figma_dev_metadata | Статус Dev Mode, аннотации, измерения, ссылки на документацию и публичные dev resources, если доступны |
Проекция по умолчанию должна быть небольшой. Большие поддеревья, text runs и бинарные данные требуют глубины, полей, лимитов и продолжения по курсору.
3. Создание узлов и изменение макета
| Инструмент | Назначение |
|---|---|
create_figma_nodes | Создание узлов Design, FigJam, Slides и Buzz с явными родителем, типом и свойствами |
update_figma_nodes | Пакетное изменение свойств узлов по ограниченному списку полей |
clone_figma_nodes | Клонирование; опционально — в целевой контейнер с сохранением трансформации относительно якоря |
move_figma_nodes | Перенос и изменение порядка через append/insert и заданные индексы |
delete_figma_nodes | Удаление заданных узлов с предварительным просмотром |
resize_figma_nodes | Изменение размера, снятие ограничений, масштабирование, блокировка/разблокировка пропорций |
combine_figma_nodes | Группировка, transform-group, flatten, разгруппировка, варианты и булевы операции |
set_figma_vector_network | Полная замена векторной сети и связанных данных векторных путей |
create_figma_nodes должен различать конструкторы rectangle, line, ellipse, polygon, star, vector, text, frame, component, page, page divider, slice, section, boolean operation, узлы FigJam и Slides, table, text path, а также узлы из JSX/SVG. Неподдерживаемые типы должны возвращать unsupported_in_editor, а не общую ошибку Plugin API.
Клонирование относительно визуального якоря использует абсолютные матрицы трансформации. Это важно, поскольку Figma вычисляет relativeTransform и координаты относительно ближайшего предка-контейнера, пропуская группы и boolean operations. Нельзя копировать исходные x/y между разными структурами родителей. Если размещение контролируется родительским auto-layout, операция должна завершиться с unsupported_placement и удалить временные копии.
4. Текст и шрифты
| Инструмент | Назначение |
|---|---|
list_figma_fonts | Список доступных шрифтов и признак отсутствующего шрифта |
update_figma_text | Вставка/удаление/замена текста, обновление типографики узла или диапазона, списков, гиперссылок, заливок, стилей, оформления, OpenType и привязок переменных |
update_figma_text_path | Изменение текста, выравнивания и векторных параметров текстовой кривой |
До записи плагин должен обнаружить и загрузить все нужные шрифты. Figma считает запись с незагруженными шрифтами недопустимой, поэтому подготовка шрифтов выполняется внутри изменения текста, а не отдельным шагом MCP-клиента.
5. Компоненты, экземпляры, слоты и варианты
| Инструмент | Назначение |
|---|---|
create_figma_component_instance | Создание экземпляра или компонента из существующего узла |
update_figma_component | Добавление/изменение/удаление свойств компонента, описаний, ссылок на документацию, вариантов и публикационной видимости |
update_figma_instance | Замена главного компонента, настройка свойств, сброс/удаление переопределений, показ вложенных экземпляров, detach или масштабирование |
update_figma_slot | Создание/сброс слотов и проверка нарушений ограничений |
list_figma_component_instances | Ограниченный список локальных экземпляров компонента |
6. Стили, переменные и библиотеки
Инструменты list_figma_styles, create_figma_style, update_figma_style, delete_figma_style и reorder_figma_styles работают с локальными paint, text, effect и grid styles, включая пагинацию и папки. list_figma_style_consumers возвращает ограниченный список узлов, использующих стиль.
list_figma_variables, create_figma_variable_collection, create_figma_variable, update_figma_variable, delete_figma_variable и bind_figma_variable читают и изменяют локальные переменные и коллекции, режимы, aliases, scopes, значения, публикационный статус и привязки к узлам, диапазонам текста, заливкам, эффектам и layout grids. list_figma_team_library_assets перечисляет доступные библиотеки и импортирует компоненты, component sets, стили или переменные по ключу.
Включать библиотеки можно только через интерфейс Figma. Plugin API умеет читать уже включённые библиотеки и импортировать известные ресурсы, но не активировать библиотеку.
7. Изображения, медиа, шейдеры, кисти и экспорт
create_figma_image создаёт изображение из ограниченного массива байтов или полученного URL; get_figma_image разрешает hash и предоставляет данные через ограниченный MCP-ресурс. create_figma_media создаёт поддерживаемые видео, GIF, link-preview или специфичные для редактора медиа-узлы. list_figma_shaders перечисляет шейдеры и импортирует их по ID; load_figma_brushes загружает поддерживаемое семейство stretch/scatter.
export_figma_nodes экспортирует заданные узлы в PNG/JPG/SVG/PDF/JSON_REST_V1 с настройками масштаба/ограничений и ресурсами для двоичных результатов. get_figma_screenshot отображает узел в PNG и возвращает его как типизированный inline MCP image. encode_figma_binary кодирует или декодирует base64 только если протокольный клиент не умеет передавать двоичные фрагменты напрямую.
Произвольный figma.fetch не должен становиться универсальным сетевым прокси. Его можно использовать внутри импорта по URL только с учётом allowlist манифеста, максимального размера ответа, MIME-проверок, тайм-аутов и политики SSRF.
8. Прототип, viewport, уведомления, undo и состояние файла
update_figma_prototype задаёт реакции, flow, поведение overlay, точки подключения и переходы Slides. get_figma_viewport читает центр, масштаб, границы и режим grid/single конкретного редактора; set_figma_viewport меняет центр/масштаб/режим или прокручивает и масштабирует к узлам.
notify_figma_user показывает ограниченное уведомление. commit_figma_undo создаёт границу undo или запускает отмену. save_figma_version сохраняет именованную контрольную точку истории версий. get_figma_file_thumbnail_node и set_figma_file_thumbnail_node читают и задают узел миниатюры файла.
openExternal, управление отображением/размером/позицией UI плагина, обмен UI-сообщениями и closePlugin должны оставаться внутренними механизмами коннектора. Они не добавляют возможностей для работы с документом и могут нарушить работу собственного bridge агента. Если управление UI извне станет требованием продукта, его следует вынести в отдельный узкий control_figma_connector_ui с ограниченным enum.
9. Данные плагина, аннотации, измерения и Dev metadata
set_figma_plugin_data задаёт/удаляет приватные и общие данные этого плагина и данные повторного запуска. Инструменты категорий аннотаций читают и создают категории; set_figma_annotations задаёт аннотации поддерживаемых узлов. manage_figma_measurements перечисляет и изменяет измерения между узлами. manage_figma_dev_resources работает со ссылками и превью ресурсов, если API доступен; set_figma_dev_status читает или изменяет поддерживаемый статус разработки.
Некоторые операции Dev Resources доступны только партнёрам или через приватный API. Обнаружение возможностей должно отличать отсутствие публичной функции от временной ошибки выполнения.
10. Motion
list_figma_animation_styles перечисляет анимационные стили Motion и нормализует параметры spring; get_figma_motion читает стили анимации узлов, анимации, ручные keyframe-треки и timeline; update_figma_motion применяет/удаляет стили, добавляет/удаляет ручные треки и задаёт длительность timeline.
Официальный Motion API находится в beta. DTO bridge для него должны иметь независимую версию схемы, а сервер должен объявлять функцию как бета-возможность.
11. Дополнения для отдельных редакторов
Такие инструменты регистрируются только при наличии подключённого плагина для нужного редактора; иначе они должны завершаться точной ошибкой о неподдерживаемой возможности.
| Инструмент | Редактор | Назначение |
|---|---|---|
get_figjam_timer, control_figjam_timer | FigJam | Чтение таймера и запуск, пауза, продолжение, остановка |
update_figjam_sticky | FigJam | Текст заметки, автор, видимость, ширина и связи stickable |
update_figjam_table | FigJam | Ячейки, вставка/удаление/перемещение/изменение размера строк и столбцов, текст ячеек |
update_figjam_connector | FigJam | Концы коннектора, наконечники, тип линии, текст и фон |
update_figjam_widget | FigJam | Клонирование виджетов и чтение/изменение синхронизированного состояния |
get_figma_canvas_grid, update_figma_canvas_grid | Slides/Buzz | Чтение и настройка 2D-сетки, создание строк и размещение узлов |
update_figma_slide | Slides | Слайды/строки, переходы, пропуск и режим просмотра |
create_figma_buzz_asset, get_figma_buzz_content, update_figma_buzz_asset | Buzz | Создание Buzz frames/instances, чтение и изменение типа ресурса, текста/медиа, smart-resize и размещения |
12. API на основе вызова и управление продуктом
Некоторые публичные API не соответствуют модели MCP-запроса и требуют отдельного пути реализации:
| API | Применение |
|---|---|
figma.codegen | Требует плагин codegen для Dev Mode и callback generate/preferences, управляемые Figma, с контрактом 15 секунд. Реализуется в отдельном режиме плагина. MCP может передать callback кэшированные шаблоны/конфигурацию. |
figma.parameters | Обрабатывает ввод Quick Actions при запуске плагина; остаётся в слое запуска плагина, вне каталога инструментов компаньона. |
figma.textreview | Требует capability text-review и пользовательского включения/выключения; допустим только отдельный режим плагина. |
figma.payments | Монетизация и оплата пользователем, а не автоматизация документа; токены оплаты и checkout не должны становиться инструментами MCP. |
figma.clientStorage | Локальное состояние коннектора; не предоставляйте произвольное чтение/запись, используйте внутри для порта и будущих настроек. |
figma.ui и showUI | UI/транспорт коннектора; не предоставляйте произвольный обмен сообщениями или HTML. |
figma.util и constants | Внутренняя проверка DTO цветов/заливок; при необходимости палитры можно вернуть через get_figma_capabilities. |
openExternal | По умолчанию не предоставлять: это видимое внешнее действие, не связанное с изменением документа. |
Глобальный fetch | Не предоставлять как свободный сетевой прокси; использовать только в ограниченных сценариях импорта ресурсов. |
Манифест и варианты публикации
Текущий манифест использует editorType: ["figma"], documentAccess: "dynamic-page" и не объявляет proposed или private API. Поэтому он не может использовать все публичные семейства, специфичные для других редакторов.
Для полного публичного покрытия можно выбрать одну из моделей:
- Рекомендуются варианты коннектора для редакторов с общим протоколом bridge. Публикуйте/собирайте варианты Design, FigJam, Slides, Buzz, Dev Mode codegen и, при необходимости, text-review. Каждый вариант запрашивает только нужные разрешения и возможности.
- Один широкий коннектор, если это разрешает Figma. Добавьте все поддерживаемые типы редакторов и публичные возможности в один манифест, затем проверяйте каждый вызов во время работы. Это увеличивает поверхность разрешений и усложняет публикацию и проверку.
Разрешения должны быть необязательными:
currentuser— только для отдельно включаемого инструмента контекста пользователя;activeusers— только для контекста совместной работы FigJam;teamlibrary— для поиска ресурсов библиотеки;paymentsне следует запрашивать для этого MCP-коннектора;codegenиtextreview— только в отдельных режимах запуска.
Не включайте enablePrivatePluginApi. Публичное покрытие намеренно исключает fileKey, партнёрские операции Dev Resources, интеграцию партнёров VS Code, приватные режимы link-preview/auth и другие приватные API Figma. Сервер должен сообщать private_api_unavailable, а не заявлять о поддержке.
Итог покрытия
Каталог охватывает все публичные семейства Plugin API из официальной документации, избегая создания отдельного MCP-инструмента для каждого свойства. Полное практическое покрытие требует нескольких десятков составных инструментов и вариантов для конкретных редакторов, а не сотен узких setters.
Архитектура разделяет публичные операции с документом/редактором, которые подходят для MCP-инструментов; API на основе callback, которым нужен отдельный режим плагина; внутренние механизмы коннектора; и приватные/партнёрские API, которые этот неофициальный коннектор не должен включать. Это покрывает автоматизируемые публичные возможности без ослабления требований к явному подключению, ограниченному объёму ответа, dynamic-page и публичному API.