Content
# Figma MCP Server (Python)
Figma Model Context Protocol (MCP) server, реализованный на Python с использованием FastMCP. Этот сервер позволяет AI ассистентам взаимодействовать с Figma через WebSocket соединение для чтения данных и анализа дизайнов.
## 🎯 Возможности
- **📖 Чтение данных**: Получение информации о документах, узлах, компонентах и стилях
- **🔍 Поиск и анализ**: Сканирование узлов по типам, поиск текстового контента
- **📤 Экспорт**: Экспорт узлов как изображений в различных форматах
- **📋 Аннотации**: Просмотр аннотаций в документах
- **🧩 Компоненты**: Работа с компонентами и их экземплярами
- **🔗 Прототипирование**: Получение информации о реакциях и связях
## 🚫 Ограничения
Для безопасности этот сервер НЕ поддерживает:
- Создание новых элементов
- Изменение стилей, цветов или текста (инструменты `set_*`)
- Операции изменения узлов (перемещение, изменение размера, удаление, клонирование)
## 📋 Доступные инструменты (15 шт.)
### 🔗 **Подключение**
- `join_channel` - Присоединиться к каналу для связи с Figma
### 📖 **Получение информации**
- `get_document_info` - Получить информацию о текущем документе Figma
- `get_selection` - Получить информацию о текущем выделении
- `read_my_design` - Получить детальную информацию о выделении включая все детали узлов
- `get_node_info` - Получить информацию о конкретном узле по ID
- `get_nodes_info` - Получить информацию о нескольких узлах
- `get_node_children` - Получить ID всех дочерних узлов с полной рекурсивной вложенностью
- `get_styles` - Получить все стили из документа
- `get_local_components` - Получить все локальные компоненты
### 🧩 **Компоненты**
- `get_instance_overrides` - Получить переопределения экземпляра компонента
### 🔍 **Поиск и сканирование**
- `scan_text_nodes` - Сканировать текстовые узлы внутри заданного узла
- `scan_nodes_by_types` - Сканировать узлы определенных типов (TEXT, RECTANGLE, FRAME)
### 📤 **Экспорт**
- `export_node_as_image` - Экспортировать узел как изображение (PNG, JPG, SVG, PDF)
### 📋 **Аннотации**
- `get_annotations` - Получить аннотации для узла или всего документа
### 🔗 **Прототипирование**
- `get_reactions` - Получить реакции (интерактивные связи) для узлов
## 🏗️ Архитектура
```
AI Client (Cursor) ←→ MCP Server ←→ WebSocket Server ←→ Figma Plugin
```
1. **MCP Server** - Предоставляет инструменты для AI
2. **WebSocket Server** - Координирует соединения и каналы
3. **Figma Plugin** - Выполняет команды в Figma
## 🚀 Быстрый старт
### 1. Установка зависимостей
```bash
cd python-version
python -m venv venv
source venv/bin/activate # Linux/Mac
# или venv\Scripts\activate # Windows
pip install -r requirements.txt
```
### 2. Запуск WebSocket сервера
```bash
python websocket_proxy.py --port 3055 --debug
```
### 3. Запуск в Figma
1. Откройте Figma Desktop
2. Перейдите в Plugins → Development → Import plugin from manifest...
3. Выберите `src/cursor_mcp_plugin/manifest.json`
4. Запустите плагин "Cursor MCP Plugin"
5. Подключитесь к серверу на порту 3055
6. Запомните Channel ID (например: `abc123xyz`)
### 4. Настройка MCP в Cursor
Добавьте следующую конфигурацию в настройки MCP Cursor (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"figma-mcp": {
"command": "python",
"args": ["-m", "src.figma_mcp.server", "--server", "localhost:3055"],
"cwd": "/path/to/your/figma_mcp"
}
}
}
```
**Альтернативный способ (с виртуальным окружением):**
```json
{
"mcpServers": {
"figma-mcp": {
"command": "/path/to/your/figma_mcp/venv/bin/python",
"args": ["/path/to/your/figma_mcp/src/figma_mcp/server.py", "--server", "localhost:3055"]
}
}
}
```
> **Примечание**: Замените `/path/to/your/figma_mcp` на реальный путь к проекту.
### 5. Запуск MCP сервера
```bash
python -m src.figma_mcp.server --server localhost:3055
```
### 6. Подключение к каналу
Используйте инструмент `join_channel` с полученным Channel ID:
```json
{
"tool": "join_channel",
"arguments": {
"channel": "abc123xyz"
}
}
```
## 🛠️ Примеры использования
### Получение информации о документе
```json
{
"tool": "get_document_info",
"arguments": {}
}
```
### Получение информации о узле
```json
{
"tool": "get_node_info",
"arguments": {
"node_id": "4472:98013"
}
}
```
### Получение всех дочерних узлов
```json
{
"tool": "get_node_children",
"arguments": {
"node_id": "4472:98012"
}
}
```
### Поиск текстовых узлов
```json
{
"tool": "scan_text_nodes",
"arguments": {
"node_id": "4472:98012",
"use_chunking": true,
"chunk_size": 50
}
}
```
### Экспорт как изображение
```json
{
"tool": "export_node_as_image",
"arguments": {
"node_id": "4472:98013",
"format": "PNG",
"scale": 2.0
}
}
```
## 🔧 Конфигурация
### WebSocket Server
- **Порт**: 3055 (по умолчанию)
- **Host**: localhost
- **Debug режим**: `--debug`
### MCP Server
- **Server URL**: localhost:3055 (по умолчанию)
- **Протокол**: MCP 2024-11-05
- **Transport**: stdio
### Cursor MCP Settings
Создайте файл `.cursor/mcp.json` в корне вашего проекта или в домашней директории:
```json
{
"$schema": "https://schema.cursor.com/mcp.json",
"mcpServers": {
"figma-mcp": {
"command": "python",
"args": ["-m", "src.figma_mcp.server", "--server", "localhost:3055"],
"cwd": "/absolute/path/to/figma_mcp",
"env": {
"PYTHONPATH": "/absolute/path/to/figma_mcp"
}
}
}
}
```
**Основные параметры:**
- `command`: Команда для запуска Python
- `args`: Аргументы для запуска MCP сервера
- `cwd`: Рабочая директория (абсолютный путь к проекту)
- `env`: Переменные окружения (опционально)
## 📁 Структура проекта
```
python-version/
├── src/figma_mcp/
│ ├── __init__.py
│ ├── server.py # Главный MCP сервер
│ ├── websocket_client.py # WebSocket клиент
│ ├── types.py # Типы Pydantic
│ └── utils.py # Утилиты
├── tests/ # Тесты (41 тест)
├── websocket_proxy.py # WebSocket сервер
├── requirements.txt # Зависимости
└── README.md # Документация
```
## 🧪 Тестирование
Запуск всех тестов:
```bash
python -m pytest tests/ -v
```
Тестирование подключения:
```bash
python test_mcp.py
```
## 🔒 Безопасность
- Фильтрация конфиденциальных данных из ответов Figma
- Валидация всех параметров с Pydantic
- Обработка ошибок и таймаутов
- Логирование в stderr для отладки
## 📦 Зависимости
- **fastmcp**: 2.4.0 - MCP сервер фреймворк
- **websockets**: 15.0.1 - WebSocket клиент/сервер
- **pydantic**: 2.11.5 - Валидация данных
- **pytest**: 8.3.5 - Тестирование
## 🐛 Отладка
1. **Проблемы с подключением**: Проверьте статус WebSocket сервера
2. **Таймауты**: Увеличьте timeout в WebSocket клиенте
3. **Ошибки каналов**: Убедитесь, что используете правильный Channel ID
4. **Логи**: Смотрите вывод в stderr для детальной информации
## 📝 Лицензия
MIT License
## 🤝 Вклад
1. Форкните репозиторий
2. Создайте ветку для функции
3. Добавьте тесты
4. Отправьте pull request
