Storybook MCP

🚀 Storybook MCP Server

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

🚀 クイックスタート

Storybook MCP Serverは、Storybookのドキュメントやコンポーネント情報とやり取りするためのツールを提供するModel Context Protocol (MCP)サーバーです。以下に、インストール、設定、使用方法を説明します。

✨ 主な機能

• getComponentList：設定されたStorybookからすべてのコンポーネントのリストを取得します。
• getComponentsProps：ヘッドレスブラウザーの自動化を使用して、複数のコンポーネントの詳細なprops情報を取得します。
• カスタムツール：JavaScriptを使用してStorybookページから任意の情報を抽出できるカスタムツールを作成します。

📦 インストール

MCP設定

MCP設定に以下の構成を追加してください。

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

環境変数

• STORYBOOK_URL (必須): Storybookのindex.jsonファイルのURL
• CUSTOM_TOOLS (オプション): Storybookから特定の情報を抽出するためのカスタムツール定義のJSON配列

💻 使用例

組み込みツール

1. getComponentList

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

例:

利用可能なコンポーネント:
Accordion
Avatar
Badge
Button
...

2. getComponentsProps

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

• プロパティ名
• 型
• デフォルト値
• 説明
• 必須/オプションの状態

パラメータ:

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

使用例:

ツール: getComponentsProps
パラメータ: { "componentNames": ["Button", "Input", "Avatar"] }

カスタムツール

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

• Storybook内の任意のページに移動する
• カスタムJavaScriptを実行してデータを抽出する
• 構造化されたデータをAIアシスタントに返す

カスタムツールの構造:

interface CustomTool {
  name: string;           // 一意のツール名
  description: string;    // AI用のツール説明
  parameters: object;     // 入力パラメータのスキーマ (オプション)
  page: string;          // 移動するURL
  handler: string;       // ページで実行するJavaScriptコード
}

カスタムツールの例:

[
  {
    "name": "getIconList",
    "description": "アイコンページからすべてのアイコンを取得する",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/icon--docs",
    "handler": "Array.from(document.querySelectorAll('.icon-name')).map(i => i.textContent)"
  },
  {
    "name": "getColorPalette",
    "description": "デザイントークンからカラーパレットを抽出する",
    "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. コンポーネントリスト: サーバーは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ブラウザーをインストールします: npx playwright install chromium
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以上
• Chromiumブラウザー（Playwrightとともに自動的にインストールされます）

エラーハンドリング

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

• 欠落または無効なStorybook URL
• ネットワーク接続問題
• コンポーネントが見つからないシナリオ
• Playwrightブラウザー自動化の失敗

📄 ライセンス

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