MCP-сервер вашей дизайн-системы: подключаем AI-агент к компонентам напрямую

«Создай карточку как в нашей системе» без MCP — агент смотрит на кодовую базу и угадывает. Находит что-то похожее на карточку, адаптирует. Результат близкий но не тот: другой border-radius, другая структура пропсов, другое имя которое теперь нужно искать и исправлять.

С MCP — агент не угадывает. Запрашивает систему напрямую: какие карточки есть, какие пропсы, как используются. Получает точный ответ. Создаёт правильный компонент.

## В чём разница на практике

Задача «создай экран настроек аккаунта».

Без MCP: Агент смотрит на кодовую базу → создаёт Input с немного другим API чем существующий, Button с другим border-radius, Card с другим именем. Результат похож визуально но не системный. 30–45 минут правок.

С Figma MCP: Агент видит открытый файл Figma → находит Input/Default, Button/Primary, Card/Default → генерирует используя реальные токены из Variables → 5–10 минут правок на детали.

Без MCP: background: #E94560          (угадал hex)
С MCP:   background: var(--color-brand-accent)   (реальный токен)

Это не про качество AI — про контекст который он получил.

## Три подхода: выбор под ситуацию

### Figma MCP — для design-first команд

Официальный Figma Dev Mode MCP Server. Агент получает прямой доступ к открытому файлу: структура слоёв, Auto Layout параметры, Variables с актуальными значениями, имена компонентов и их пропсы в Figma.

Когда: Figma — source of truth, команда design-first, Tokens Studio синхронизирует Variables с кодом.

Как подключить:

1. Установи Claude Code Desktop
2. Settings → MCP Servers → Add server
3. Figma Dev Mode MCP Server (figma.com/developers/mcp)
4. Открой нужный файл в Figma — агент видит его автоматически

Что подготовить заранее: компоненты с осмысленными именами (не «Group 47»), Variables подключены к компонентам, Tokens Studio настроен.

Время настройки: 15–30 минут если система уже готова.

### Storybook MCP — для code-first команд

Storybook генерирует component manifest — JSON со всеми метаданными: имена компонентов, TypeScript-типы пропсов, примеры из stories, документация из MDX-страниц. Агент читает manifest и знает реальную систему в продакшене.

Ключевое отличие от Figma MCP: Storybook показывает что есть в коде, не в дизайне. Если Figma и код разошлись — Storybook показывает правду. Для code-first команд это важнее чем дизайн-файл.

Дополнительно: autonomous correction loop. Агент создаёт компонент, запускает interaction tests и accessibility tests из Storybook, видит что не прошло, исправляет. Разработчик вмешивается когда тесты зелёные.

Когда: код — source of truth, React design system с CI, команда code-first.

npm install --save-dev @storybook/addon-mcp
# В .storybook/main.ts:
addons: ['@storybook/addon-mcp']
# В Claude Code MCP Settings:
# name: storybook, url: http://localhost:6006/mcp

### Кастомный MCP-сервер

Если система живёт в нескольких местах (Figma + Storybook + внутренний portal) — кастомный сервер агрегирует из всех источников и предоставляет единый интерфейс. SDK на TypeScript и Python, документация на modelcontextprotocol.io.

## AGENTS.md для работы с MCP

## Дизайн-система — алгоритм работы

MCP подключён. Перед созданием UI-компонента:
1. Запроси список компонентов через MCP
2. Найди подходящий существующий
3. Прочитай его документацию и пропсы
4. Используй существующий — не создавай новый

Если подходящего нет:
- Скажи явно какого компонента не хватает
- Предложи ближайший существующий как основу
- НЕ создавай молча новый компонент

Запрещено без явного запроса:
- Новые варианты Button/* или Card/*
- Захардкоженные hex вместо токенов
- Изменения в src/lib/billing/** и src/lib/auth/**

## Дашборд расхождений: Figma vs Storybook

Один из ценнейших use cases: агент сравнивает дизайн и код, находит расхождения.

Через Figma MCP: список всех компонентов в файле [название файла].
Через Storybook MCP: список всех компонентов в Storybook.

Создай таблицу:
| Компонент       | Figma | Storybook | Статус             |
|-----------------|-------|-----------|-------------------|
| Button/Primary  | ✅    | ✅        | Синхронизирован    |
| Card/Featured   | ✅    | ❌        | Нет в коде         |
| Toast/Error     | ❌    | ✅        | Нет в дизайне      |

Для "Нет в коде": приоритет реализации по частоте использования в Figma.
Для "Нет в дизайне": используется ли в продакшене? Нужно ли добавить в Figma?

Это ежедневный health-check без ручного аудита раз в квартал.

## Что делать если MCP недоступен

Иногда MCP временно недоступен. AGENTS.md с детальным описанием системы — лучший fallback:

## Компоненты (v1.3.0, актуально на июнь 2026)

Button:
- variant: "primary" | "secondary" | "ghost" | "danger", default "primary"
- size: "sm" | "md" | "lg", default "md"
- disabled: boolean, loading: boolean
Использовать: <Button variant="primary" size="md">Текст</Button>

Input:
- label: string (обязательно), error: string (опционально)
- disabled: boolean, placeholder: string
Использовать: <Input label="Email" type="email" error={errorMsg} />

Это не замена MCP — но позволяет AI работать точнее при недоступности.

## Тестовый промпт для проверки подключения

Проверь что MCP дизайн-системы работает корректно.

1. Через MCP получи список всех компонентов типа Button.
2. Для Button/Primary покажи все пропсы с TypeScript-типами.
3. Создай форму входа ТОЛЬКО из компонентов которые есть в MCP:
   - поле email, поле password
   - кнопка "Войти" (Primary)
   - ссылка "Забыл пароль"
4. Перечисли точные имена всех использованных компонентов.

Важно: если компонент не нашёл через MCP — скажи явно. Не придумывай.

## Типичный путь команды: от «нам не нужен MCP» до «не понимаем как работали без»

Многие команды начинают со скептицизма. «У нас уже есть AGENTS.md с описанием компонентов — зачем MCP?»

AGENTS.md описывает систему текстом. MCP даёт агенту прямой доступ к актуальным данным. Разница становится очевидной когда система меняется.

Сценарий: разработчик добавил новый пропс к Button. Обновил код. Обновил Storybook. Забыл обновить AGENTS.md. AI продолжает генерировать Button без нового пропса — потому что читает устаревший AGENTS.md.

С MCP: агент запрашивает актуальное состояние Button из Storybook — видит новый пропс. Без обновления документации вручную.

MCP — это разница между «AI знает как система была описана» и «AI знает какой система является прямо сейчас».

## Когда MCP не решает проблему

MCP показывает что система делает. Но не объясняет почему.

«Button/Danger использовать только с confirm-диалогом» — это правило которое нужно явно написать в AGENTS.md. MCP покажет что Button/Danger существует и какие у него пропсы. Не покажет когда его использовать.

MCP и AGENTS.md дополняют друг друга: MCP даёт актуальные данные о компонентах, AGENTS.md — правила их использования. Вместе — у AI есть и инструменты, и контекст как их применять.

## Что MCP не заменяет

Важно понимать чего MCP не делает, чтобы не возлагать на него неправильные ожидания.

MCP не заменяет DESIGN.md и AGENTS.md. MCP даёт агенту данные о компонентах — пропсы, варианты, примеры. AGENTS.md даёт правила — когда использовать primary, когда secondary, что запрещено. Нужны оба.

MCP не исправляет плохо организованную систему. Если компоненты названы «Component_47» и «Group_203» — MCP будет возвращать эти имена. Агент не сможет с ними работать осмысленно. MCP работает настолько хорошо насколько хорошо организована система.

MCP не устраняет необходимость ревью. Агент с MCP генерирует более точный код — но не идеальный. Edge cases, бизнес-логика, UX-решения — всё это требует человеческого ревью.

MCP — это инструмент который снижает количество итераций и улучшает первый вариант. Это ценно само по себе, без ожидания что агент будет работать полностью автономно.

## Путь команды от скептицизма до «не понимаем как работали без»

Многие команды начинают с «нам не нужен MCP, у нас есть AGENTS.md». Скептицизм понятен.

AGENTS.md описывает систему текстом в конкретный момент времени. MCP даёт агенту доступ к актуальным данным. Разница проявляется при изменениях.

Разработчик добавил новый пропс к Button. Обновил код и Storybook. Забыл обновить AGENTS.md. С AGENTS.md — AI продолжает генерировать Button без нового пропса. С MCP — агент видит актуальное состояние компонента, новый пропс доступен.

Первый раз когда команда сталкивается с этим расхождением — становится понятно ценность MCP. Не «нужно обновить документацию», а «система всегда показывает актуальное состояние».

Типичный путь: установить MCP → использовать неделю → заметить что AI больше не угадывает имена компонентов → начать чаще использовать → перестать мыслить без него.

Один практический совет для начала: не пытайся настроить всё идеально до запуска MCP. Подключи Figma MCP или Storybook MCP в текущем состоянии системы. AI сразу начнёт использовать правильные имена компонентов — даже если система неполная. Улучшения системы будут сразу отражаться в качестве генерации.

☐ Подход выбран: Figma MCP / Storybook MCP / кастомный
☐ Компоненты именованы осмысленно (не Component_47)
☐ Пропсы задокументированы в Storybook stories / Figma
☐ Тестовый промпт прошёл: агент использует компоненты из системы
☐ AGENTS.md содержит инструкцию: запрашивать MCP перед созданием
☐ Fallback: список компонентов с API в AGENTS.md
☐ Через неделю: аудит нового кода — система используется?