Storybook MCP サーバー

Storybook のドキュメントやコンポーネント情報とやり取りするためのツールを提供する Model Context Protocol (MCP) サーバーです。

機能

• getComponentList: 設定された Storybook から全コンポーネントのリストを取得します

• getComponentsProps: ヘッドレスブラウザの自動化を使用して、複数のコンポーネントの詳細な props 情報を取得します

• Custom Tools: JavaScript を使用して Storybook ページから任意の情報を抽出できるカスタムツールを作成します

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 (必須): Storybook の index.json ファイルへの URL

• CUSTOM_TOOLS (任意): Storybook から特定の情報を抽出するためのカスタムツール定義の JSON 配列

使用方法

このサーバーは組み込みツールを提供し、カスタムツールもサポートしています：

組み込みツール

1. getComponentList

設定された Storybook から利用可能な全コンポーネントのリストを取得します。

例:

Available components:
Accordion
Avatar
Badge
Button
...

2. getComponentsProps

複数のコンポーネントの詳細な props 情報を取得します。これには以下が含まれます：

• プロパティ名

• 型

• デフォルト値

• 説明

• 必須/任意ステータス

パラメータ:

• componentNames (文字列の配列): props 情報を取得するコンポーネント名の配列

使用例:

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

カスタムツール

Storybook ページから特定の情報を抽出するためのカスタムツールを定義できます。各カスタムツールは以下のことが可能です：

• Storybook 内の任意のページへ移動

• カスタム JavaScript を実行してデータを抽出

• AI アシスタントに構造化データを返す

カスタムツールの構造:

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 を参照してください。

例

STORYBOOK_URL と CUSTOM_TOOLS 環境変数を使用して Spectrum storybook-mcp 設定を行います。

{
  "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. コンポーネントリスト: サーバーは Storybook の index.json ファイル（v3 は stories.json）を取得し、「docs」タイプとしてマークされたすべてのコンポーネントを抽出します

2. Props 情報: コンポーネントの props について、サーバーは以下を行います：

   • index.json からコンポーネントのドキュメント ID を検索

   • コンポーネントのドキュメントページ用の iframe URL を構築

   • Playwright を使用してヘッドレスブラウザでページを読み込み

   • ドキュメントから props テーブルの HTML を抽出

サポートされている Storybook URL

このサーバーは index.json ファイル（v3 は stories.json）を公開しているすべての Storybook で動作します。一般的なパターン：

• 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

注: 必要に応じて yarn dev の代わりに npx @modelcontextprotocol/inspector tsx src/index.ts を使用することもできます。

ビルド

yarn build

テスト

yarn test

要件

• Node.js 18.0.0 以上

• Playwright によってインストールされた Chromium ブラウザ

エラーハンドリング

サーバーには以下に対する包括的なエラーハンドリングが含まれています：

• Storybook URL の欠落または無効

• ネットワーク接続の問題

• コンポーネントが見つからないシナリオ

• Playwright ブラウザ自動化の失敗

ライセンス

Storybook MCP は MIT ライセンス の下で提供されています。