Storybook MCP Server

Сервер протокола контекста модели (MCP), предоставляющий инструменты для взаимодействия с документацией Storybook и информацией о компонентах.

Возможности

• getComponentList: Получение списка всех компонентов из настроенного Storybook

• getComponentsProps: Получение подробной информации о пропсах для нескольких компонентов с использованием автоматизации headless-браузера

• Custom Tools: Создание пользовательских инструментов, которые могут извлекать любую информацию со страниц вашего Storybook с помощью JavaScript

Related MCP server: MCP Server

Установка и настройка

Настройки MCP

Добавьте следующую конфигурацию в настройки MCP:

{
  "mcpServers": {
    "storybook": {
      "command": "npx",
      "args": ["-y", "storybook-mcp@latest"],
      "env": {
        "STORYBOOK_URL": "<your_storybook_url>/index.json"
      }
    }
  }
}

storybook-mcp запускается немедленно и при первом запуске устанавливает Chromium в фоновом режиме. Если вы хотите предварительно установить браузер, выполните npx -y storybook-mcp@latest install-browser. До завершения этой загрузки первый вызов инструмента, использующего браузер, может занять больше времени.

Переменные окружения

• STORYBOOK_URL (обязательно): URL-адрес файла index.json вашего Storybook

• CUSTOM_TOOLS (опционально): JSON-массив определений пользовательских инструментов для извлечения конкретной информации из вашего Storybook

Использование

Сервер предоставляет встроенные инструменты и поддерживает пользовательские:

Встроенные инструменты

1. getComponentList

Извлекает список всех доступных компонентов из настроенного Storybook.

Пример:

Available components:
Accordion
Avatar
Badge
Button
...

2. getComponentsProps

Получает подробную информацию о пропсах для нескольких компонентов, включая:

• Имена свойств

• Типы

• Значения по умолчанию

• Описания

• Статус обязательности/опциональности

Параметры:

• componentNames (массив строк): Массив имен компонентов, для которых нужно получить информацию о пропсах

Пример использования:

Tool: getComponentsProps
Parameters: { "componentNames": ["Button", "Input", "Avatar"] }

Пользовательские инструменты

Вы можете определить пользовательские инструменты для извлечения конкретной информации со страниц вашего Storybook. Каждый пользовательский инструмент может:

• Переходить на любую страницу в вашем Storybook

• Выполнять произвольный JavaScript для извлечения данных

• Возвращать структурированные данные ИИ-ассистенту

Структура пользовательского инструмента:

interface CustomTool {
  name: string; // Unique tool name
  description: string; // Tool description for the AI
  parameters: object; // Input parameters schema (optional)
  page: string; // URL to navigate to
  handler: string; // JavaScript code to execute on the page
}

Примеры пользовательских инструментов:

[
  {
    "name": "getIconList",
    "description": "Get All Icons from the Icon page",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/icon--docs",
    "handler": "Array.from(document.querySelectorAll('.icon-name')).map(i => i.textContent)"
  },
  {
    "name": "getColorPalette",
    "description": "Extract color palette from design tokens",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/design-tokens--colors",
    "handler": "Array.from(document.querySelectorAll('.color-swatch')).map(el => ({ name: el.getAttribute('data-color-name'), value: el.style.backgroundColor }))"
  }
]

Дополнительные примеры и подробную документацию см. в examples/custom-tools-example.md.

Пример

Настройте конфигурацию Spectrum для storybook-mcp с помощью переменных окружения STORYBOOK_URL и CUSTOM_TOOLS.

{
  "mcpServers": {
    "storybook-mcp": {
      "command": "npx",
      "args": ["-y", "storybook-mcp@latest"],
      "env": {
        "STORYBOOK_URL": "https://opensource.adobe.com/spectrum-web-components/storybook/index.json",
        "CUSTOM_TOOLS": "[{\"name\":\"getIconList\",\"description\":\"Get All Icons from the Icon page\",\"parameters\":{},\"page\":\"https://opensource.adobe.com/spectrum-web-components/storybook/iframe.html?viewMode=docs&id=icons--docs&globals=\",\"handler\":\"Array.from(document.querySelector('icons-demo').shadowRoot.querySelectorAll('.icon')).map(i => i.textContent)\"}]"
      }
    }
  }
}

Как это работает

1. Список компонентов: Сервер получает файл index.json (в v3 это stories.json) из Storybook и извлекает все компоненты, помеченные типом "docs"

2. Информация о пропсах: Для пропсов компонентов сервер:

   • Находит ID документации компонента из index.json

   • Формирует URL iframe для страницы документации компонента

   • Использует Playwright для загрузки страницы в headless-браузере

   • Извлекает HTML таблицы пропсов из документации

Поддерживаемые URL Storybook

Сервер работает с любым Storybook, который предоставляет файл index.json (в v3 это stories.json). Распространенные шаблоны:

• https://your-storybook-domain.com/index.json

• https://your-storybook-domain.com/storybook/index.json

Разработка

Локальная разработка

1. Клонируйте репозиторий

2. Установите зависимости: yarn install

3. Установите браузеры Playwright: yarn install:browser

4. Установите переменную окружения: export STORYBOOK_URL="your-storybook-url"

5. Запустите в режиме разработки: yarn dev

Примечание: Вы также можете использовать npx @modelcontextprotocol/inspector tsx src/index.ts вместо yarn dev, если предпочитаете.

Сборка

yarn build

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

yarn test

Требования

• Node.js 18.0.0 или выше

• Браузер Chromium, установленный через Playwright

Обработка ошибок

Сервер включает комплексную обработку ошибок для:

• Отсутствующих или неверных URL Storybook

• Проблем с сетевым подключением

• Сценариев, когда компонент не найден

• Сбоев автоматизации браузера Playwright

Лицензия

Storybook MCP распространяется под лицензией MIT.