FAQ#

Русский | 简体中文 | English

#Агенты / MCP-клиенты

#Какие клиенты поддерживаются?

Любой stdio-хост MCP может запускать npx -y figma-agent-mcp. Мы документируем:

Cursor · Claude Code · Codex · Qoder · CodeBuddy · Trae — см. Подключение ИИ-агентов (中文：接入 AI Agent).

#Мой клиент настроен, но инструменты не работают / показывают Not connected

1. Убедитесь, что мост плагина Figma зелёный
2. Убедитесь, что клиент действительно запустил MCP (npx / Node в PATH)
3. Следуйте разделу для конкретного клиента в agent-setup.md
4. См. Мост / подключение ниже

#Мост / подключение

#list_files возвращает «Not connected» или пустой результат

1. Откройте файл в Figma Desktop и запустите Figma Agent Kit
2. Убедитесь, что индикатор моста плагина зелёный
3. Убедитесь, что только один исправный Leader использует порт 1998 (lsof -iTCP:1998 -sTCP:LISTEN)
4. Перезапустите Cursor MCP / npx figma-agent-mcp после остановки оставшихся Node-процессов на этом порту
5. Сверьте версии: ZIP плагина и figma-agent-mcp должны иметь одну версию 0.1.x

#Порт уже используется / MCP всегда follower

Старый процесс MCP может всё ещё занимать 1998. Остановите оставшиеся прослушивающие процессы node, затем перезапустите MCP агента, чтобы новый Leader привязал порт. Плагин переподключится.

#MsgPack codec not loaded в плагине

Пересоберите плагин (pnpm build), чтобы codec, добавленный esbuild, присутствовал в ui.html / code.js, затем перезагрузите Development-плагин. Не запускайте старый плагин с MCP только на MsgPack.

#Локальные / несохранённые файлы показывают fileKey: "unknown" или local-…

Это ожидаемо для несохранённых файлов Desktop. При необходимости плагин сохраняет стабильный локальный ключ в корневом pluginData. Сохраните файл в Figma cloud, если нужен облачный fileKey.

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

#Инструменты Motion завершаются ошибкой возможности

Для Motion нужна сборка Figma, предоставляющая figma.motion / applyAnimationStyle. Обновите Figma Desktop или не используйте эти инструменты.

#Ошибка валидации .type у apply_animation_style

Для встроенных пресетов передавайте animationStyleData: { "type": "FIGMA", … } (дискриминатор — FIGMA | USER), а не имя пресета затухания в качестве type.

#Скриншоты слишком большие / контекст агента переполняется

Используйте save_screenshots с compress: true (по умолчанию для PNG) и записывайте на диск. Предпочтите get_screenshot только для небольших предпросмотров. Соответствие срезам: scale: 3.

#getNodeById / узел не найден после переключения страницы

Плагин использует documentAccess: "dynamic-page" и getNodeByIdAsync. Используйте свежую версию плагина/MCP с поддержкой getNodeByIdAsync. Передавайте верный fileKey, когда подключено несколько файлов.

#ИИ (интерфейс плагина)

#Пользовательский LLM-хост заблокирован

Добавьте хост в manifest.json → networkAccess.allowedDomains, пересоберите и повторно импортируйте. См. Возможности ИИ.

#Нужен ли MCP мой ключ OpenAI?

Нет. Ключ из clientStorage используют только вкладки Rename / Group.

#Установка / версии

#Должны ли совпадать версии MCP и плагина?

Да. Изменения протокола (MsgPack, формы инструментов) требуют совместного обновления. При публикации предпочтите pnpm release:kit:*.

#Где находится пакет npm и ZIP плагина?

#Всё ещё не получается?

Создайте issue, указав: ОС, версию Figma Desktop, версию MCP (npx figma-agent-mcp / версию пакета), версию плагина из UI и работают ли list_files / индикатор моста. Для сообщений об уязвимостях (не в публичных issue) см. SECURITY.md.