Перейти к содержимому

Покрытие Figma Plugin API ​

Область и первоисточники ​

Документ сопоставляет публичный Figma Plugin API с возможностями MCP для локальной архитектуры компаньона. Использованы официальные материалы Figma:

Также изучены связанные с глобальным объектом публичные 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. Кроме того:

  1. Используйте стабильные составные инструменты. Представляйте чтение и запись свойств типизированными проекциями и наборами изменений вместо сотен специализированных инструментов.
  2. Ограничивайте каждый результат чтения. Используйте явный набор полей, глубину обхода, лимиты результатов и курсоры продолжения. Большие экспорты и медиа возвращайте как MCP-ресурсы или по частям, а не одним JSON.
  3. Полностью инициализируйте отслеживание изменений. Один раз вызовите loadAllPagesAsync() перед регистрацией documentchange: Figma требует этого в dynamic-page. Bridge должен ждать завершения инициализации, чтобы учитывать ручные изменения и изменения через коннектор.
  4. Последовательно выполняйте записи внутри подключения. Сохраняйте последовательность запросов одного плагина, разрешая чтение по другим подключениям параллельно.
  5. Делайте записи проверяемыми. Изменяющие инструменты должны поддерживать dry_run, idempotency_key и ограниченную пакетную операцию, а также возвращать ID созданных, изменённых и удалённых узлов и предупреждения.
  6. Сохраняйте семантику Figma. Не сериализуйте необработанные proxy-объекты Figma. Преобразуйте заливки, эффекты, векторы, переменные, стили, реакции и другие значения в версионные DTO.
  7. Объявляйте возможности среды выполнения. Доступный API зависит от типа редактора, режима, разрешений манифеста, возможностей, статуса публикации плагина, а также публичности и бета-статуса API.
  8. Точно аннотируйте 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_timerFigJamЧтение таймера и запуск, пауза, продолжение, остановка
update_figjam_stickyFigJamТекст заметки, автор, видимость, ширина и связи stickable
update_figjam_tableFigJamЯчейки, вставка/удаление/перемещение/изменение размера строк и столбцов, текст ячеек
update_figjam_connectorFigJamКонцы коннектора, наконечники, тип линии, текст и фон
update_figjam_widgetFigJamКлонирование виджетов и чтение/изменение синхронизированного состояния
get_figma_canvas_grid, update_figma_canvas_gridSlides/BuzzЧтение и настройка 2D-сетки, создание строк и размещение узлов
update_figma_slideSlidesСлайды/строки, переходы, пропуск и режим просмотра
create_figma_buzz_asset, get_figma_buzz_content, update_figma_buzz_assetBuzzСоздание 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 и showUIUI/транспорт коннектора; не предоставляйте произвольный обмен сообщениями или HTML.
figma.util и constantsВнутренняя проверка DTO цветов/заливок; при необходимости палитры можно вернуть через get_figma_capabilities.
openExternalПо умолчанию не предоставлять: это видимое внешнее действие, не связанное с изменением документа.
Глобальный fetchНе предоставлять как свободный сетевой прокси; использовать только в ограниченных сценариях импорта ресурсов.

Манифест и варианты публикации ​

Текущий манифест использует editorType: ["figma"], documentAccess: "dynamic-page" и не объявляет proposed или private API. Поэтому он не может использовать все публичные семейства, специфичные для других редакторов.

Для полного публичного покрытия можно выбрать одну из моделей:

  1. Рекомендуются варианты коннектора для редакторов с общим протоколом bridge. Публикуйте/собирайте варианты Design, FigJam, Slides, Buzz, Dev Mode codegen и, при необходимости, text-review. Каждый вариант запрашивает только нужные разрешения и возможности.
  2. Один широкий коннектор, если это разрешает 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.

Документация Figma MCP v2.0.0. Распространяется по лицензии MIT.