Storybook MCP

Storybook MCP — Руководство для контрибьюторов

Добро пожаловать в монорепозиторий аддона Storybook MCP! Этот проект позволяет 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. Использовать сборку VSCode Insiders
2. Убедиться, что параметр chat.mcp.apps.enabled включён
3. Запустить Storybook репозитория в режиме отслеживания, выполнив pnpm storybook в корне
4. Перезапустить VSCode, открыть файл .vscode/mcp.json и убедиться, что Storybook MCP отмечен как «Running», иначе нажать «Start»
5. Открыть чат в VSCode и написать примерно такой запрос:

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

6. После этого первого запроса, когда вы вносите изменения, Storybook автоматически перезапускается. Дождитесь полной готовности, затем можете отправить запрос «Запусти инструмент снова».

Вы также можете использовать инспектор от 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 pkg from '../package.json' with { type: 'json' };

🚢 Процесс выпуска

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

# 1. Create a changeset describing your changes
pnpm changeset

При создании PR добавьте changeset, если ваши изменения должны инициировать выпуск:

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

🤝 Участие в разработке

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

1. Сделайте форк репозитория и создайте feature-ветку
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.