Storybook MCP

[!TIP] Этот репозиторий перемещён в storybookjs/storybook начиная с Storybook v10.6.0. Пожалуйста, обращайтесь туда за обновлённой документацией.

---

Storybook MCP

Добро пожаловать в монорепозиторий Storybook MCP Addon! Этот проект позволяет AI-агентам работать эффективнее со Storybook, предоставляя MCP (Model Context Protocol) сервер, который раскрывает информацию о UI-компонентах и рабочие процессы разработки.

📦 Пакеты

Этот монорепозиторий содержит четыре основных пакета:

• @storybook/mcp — автономная MCP-библиотека для предоставления знаний о компонентах Storybook (может использоваться независимо)
• @storybook/addon-mcp — аддон Storybook, который запускает MCP-сервер внутри вашего dev-сервера Storybook и включает функциональность @storybook/mcp из вашего локального Storybook
• @storybook/claude-code-plugin — плагин Claude Code с навыками настройки Storybook и конфигурацией MCP
• @storybook/codex-plugin — плагин Codex с навыками настройки Storybook и конфигурацией MCP

Каждый пакет имеет собственный README с пользовательской документацией. Этот документ предназначен для контрибьюторов, желающих разрабатывать, тестировать или вносить вклад в эти пакеты.

🚀 Быстрый старт

Тестирование плагинов Claude и Codex из GitHub

Внешние тестировщики могут установить маркетплейс плагинов непосредственно из ветки main этого репозитория. Локальное клонирование не требуется.

Codex (подробнее)

codex plugin marketplace add storybookjs/mcp --ref main
codex plugin add storybook@storybook

Проверьте маркетплейс и плагин:

codex plugin marketplace list
codex plugin list --marketplace storybook

Claude Code (подробнее)

claude plugin marketplace add storybookjs/mcp@main --scope user
claude plugin install storybook@storybook --scope user

Проверьте плагин и MCP-сервер:

claude plugin list --json
claude mcp list

Репозиторий намеренно хранит каталоги маркетплейсов в двух местах. Корневые каталоги поддерживают установки из GitHub с ветки storybookjs/mcp; локальные каталоги пакетов поддерживают локальные скрипты разработки пакетов. Они должны оставаться идентичными, за исключением относительного пути к исходному коду плагина, и проверка пакетов гарантирует это.

Предварительные требования

• Node.js 24+ — проект требует Node.js 24 или выше (см. .nvmrc)
• pnpm 10.19.0+ — строгое требование к менеджеру пакетов (обеспечивается в package.json)

# Use the correct Node version
nvm use

# Install pnpm if you don't have it
npm install -g pnpm@10.19.0

Установка

# Clone the repository
git clone https://github.com/storybookjs/mcp.git
cd addon-mcp

# Install all dependencies (for all packages in the monorepo)
pnpm install

Рабочий процесс разработки

# Build all packages
pnpm build

# Start development mode (watches for changes in all packages)
pnpm dev

# Run unit tests in watch mode
pnpm test

# Run unit tests once
pnpm test:run

# Run Storybook with the addon for testing
pnpm --filter internal-storybook storybook

Команда Storybook запускает:

• Внутренний тестовый экземпляр Storybook на http://localhost:6006
• Аддон в режиме наблюдения, чтобы изменения отражались автоматически
• MCP-сервер, доступный на http://localhost:6006/mcp

🛠️ Часто выполняемые задачи

Разработка

Команда turbo watch build запускает все пакеты в режиме наблюдения, автоматически пересобирая их при изменениях:

# Start development mode for all packages
pnpm turbo watch build

# This is usually all you need - starts Storybook AND watches addon for changes
pnpm storybook

Сборка

# Build all packages
pnpm build

Тестирование

Монорепозиторий использует централизованную конфигурацию Vitest на корневом уровне с проектами, настроенными для каждого пакета:

# Watch tests across all packages
pnpm test

# Run tests once across all packages
pnpm test:run

# Run tests with coverage and CI reporters
pnpm test:ci

Отладка MCP-серверов

Используйте MCP Inspector для отладки и тестирования функциональности MCP-сервера:

# Launches the MCP inspector (requires Storybook to be running)
pnpm inspect

Это использует конфигурацию в .mcp.inspect.json для подключения к вашим локальным MCP-серверам.

В качестве альтернативы вы также можете использовать эти команды curl, чтобы проверить, что всё работает:

# test that the mcp server is running
# use port 6006 to test the addon-mcp server instead
curl -X POST \
  http://localhost:13316/mcp      \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# test a specific tool call
curl -X POST http://localhost:13316/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list-all-documentation",
      "arguments": {}
    }
  }'

Отладка со Storybook

Вы можете запустить Storybook с помощью:

pnpm storybook

Это соберёт всё и запустит Storybook с addon-mcp, после чего вы сможете подключить своего агента кодирования к нему на http://localhost:6006/mcp (или вашем настроенном аддон-эндпоинте) и попробовать.

Работа с MCP-приложением

Чтобы работать с MCP-приложением и отлаживать его, которое отображается как часть инструмента preview-stories, вы можете:

1. Использовать Insiders-сборку VSCode
2. Убедиться, что включена настройка chat.mcp.apps.enabled
3. Запустить Storybook репозитория в режиме наблюдения, выполнив pnpm storybook в корне
4. Перезапустить VSCode, открыть файл .vscode/mcp.json и убедиться, что Storybook MCP отмечен как Running, в противном случае нажмите Start.
5. Открыть чат в VSCode и написать запрос, например:

Покажи мне, как выглядят все истории кнопок, используя Storybook MCP

6. После этого первого запроса, при каждом изменении Storybook автоматически перезапускается. Дождитесь полной готовности, затем отправьте запрос "Run the tool again".

Вы также можете использовать инспектор от MCPJam для более низкоуровневого контроля вызовов инструментов.

Форматирование и линтинг

# Format all files with Prettier
pnpm format

# Check formatting without changing files
pnpm format:check

# Lint code with oxlint
pnpm lint

# Lint with GitHub Actions format (for CI)
pnpm lint:ci

# Check package exports with publint
pnpm publint

🔍 Проверки качества

Монорепозиторий включает несколько проверок качества, которые выполняются в CI:

# Run all checks (build, test, lint, format, typecheck, publint)
pnpm check

# Run checks in watch mode (experimental)
pnpm check:watch

# Type checking (uses tsc directly, not turbo)
pnpm typecheck

# Type checking with turbo (for individual packages)
pnpm turbo:typecheck

# Testing with turbo (for individual packages)
pnpm turbo:test

📝 Соглашения по коду

TypeScript и импорты

Всегда включайте расширения файлов в относительных импортах:

// ✅ Correct
import { foo } from './bar.ts';

// ❌ Wrong
import { foo } from './bar';

• JSON-импорты используют синтаксис import attributes:

import pkg from '../package.json' with { type: 'json' };

🚢 Процесс релиза

Этот проект использует Changesets для управления версиями:

# 1. Create a changeset describing your changes
pnpm changeset

Когда вы создаёте PR, добавьте changeset, если ваши изменения должны вызвать релиз:

• Patch: Исправления ошибок, обновления документации
• Minor: Новые функции, обратно совместимые изменения
• Major: Критические изменения

🤝 Вклад в проект

Мы приветствуем вклад! Вот как начать:

1. Сделайте форк репозитория и создайте ветку для функции
2. Внесите изменения, следуя соглашениям по коду выше
3. Протестируйте изменения, используя внутренний экземпляр Storybook
4. Создайте changeset, если ваши изменения требуют релиза
5. Отправьте pull request с понятным описанием

Перед отправкой

• Код собирается без ошибок (pnpm build)
• Тесты проходят (pnpm test:run)
• Код отформатирован (pnpm format)
• Код прошёл линтинг (pnpm lint)
• Проверка типов проходит (pnpm typecheck)
• Изменения протестированы с MCP inspector или внутренним Storybook
• Changeset создан при необходимости (pnpm changeset)

Получение помощи

• Идеи и запросы функций: Начать обсуждение
• Отчёты об ошибках: Открыть issue
• Вопросы: Задавайте в GitHub Discussions

📄 Лицензия

MIT — см. LICENSE для подробностей

---

Примечание: Этот проект является экспериментальным и активно развивается. API и архитектура могут меняться по мере исследования лучших способов интеграции AI-агентов со Storybook.