MCP Design System Extractor

🚀 MCP Design System Extractor

Model Context Protocol (MCP)サーバーで、Storybookデザインシステムからコンポーネント情報を抽出します。Storybookインスタンス（https://storybook.js.org の配布物を含む）に接続し、HTML、スタイル、およびコンポーネントのメタデータを抽出します。

✨ 主な機能

• 🔍 コンポーネントの一覧表示：Storybookから利用可能なすべてのコンポーネントを取得します。
• 📄 HTMLの抽出：動的JavaScriptをサポートした任意のコンポーネントバリアントのレンダリングされたHTMLを取得します。
• 🔎 コンポーネントの検索：名前、タイトル、またはカテゴリでコンポーネントを検索します。
• 🎛️ コンポーネントのプロパティ：型やデフォルト値を含むコンポーネントのプロパティ/APIドキュメントを取得します。
• 🔗 コンポーネントの依存関係：他のコンポーネント内で使用されているコンポーネントを分析します。
• 📐 レイアウトコンポーネント：グリッド、コンテナ、スタックなどのすべてのレイアウトコンポーネントを例とともに取得します。
• 🎨 テーマ情報：デザインシステムのテーマ（色、間隔、タイポグラフィ、ブレークポイント）を抽出します。
• 🎯 目的別検索：目的（フォーム入力、ナビゲーション、フィードバック）でコンポーネントを検索します。
• 🧩 コンポーネントの組み合わせ例：コンポーネントがどのように組み合わされるかの例を取得します。
• 📝 外部CSSの分析：CSSファイルを取得して分析し、デザイントークンと変数を抽出します。

🚀 クイックスタート

npm install && npm run build
npm run setup  # Claude Desktopの対話型セットアップ

または、手動で設定します：

export STORYBOOK_URL=http://localhost:6006

💻 使用例

基本的な使用法

// すべてのコンポーネントをリストする（最初のステップとしておすすめ）
await listComponents({ category: "all" });

// ワイルドカードを使用してすべてのコンポーネントを検索する
await searchComponents({ query: "*", searchIn: "all" });

// 特定のコンポーネントを検索する
await searchComponents({ query: "button", searchIn: "name" });

// 特定のコンポーネントのすべてのバリアントを取得する
await getComponentVariants({ componentName: "Button" });

// 特定のボタンバリアントのHTMLを取得する（上記の正確なストーリーIDを使用）
await getComponentHTML({ 
  componentId: "button--primary",
  includeStyles: true 
});

// コンポーネントのプロパティドキュメントを取得する
await getComponentProps({
  componentId: "button--primary"
});

// 目的別にコンポーネントを検索する
await getComponentByPurpose({
  purpose: "form inputs"
});

// 例付きでレイアウトコンポーネントを取得する
await getLayoutComponents({
  includeExamples: true
});

// テーマ情報を抽出する
await getThemeInfo({
  includeAll: false
});

// コンポーネントの依存関係を分析する
await getComponentDependencies({
  componentId: "card--default"
});

// コンポーネントの組み合わせ例を取得する
await getComponentCompositionExamples({
  componentId: "button--primary",
  limit: 3
});

// 推奨：デザイントークンのみを抽出する（レスポンスが小さく、トークン制限を回避）
await getExternalCSS({
  cssUrl: "https://my-storybook.com/assets/main.css"
  // extractTokens: true (default), includeFullCSS: false (default)
});

// CSSコンテンツが必要な場合のみ（トークン制限に達する可能性がある）
await getExternalCSS({
  cssUrl: "./assets/tokens.css",
  includeFullCSS: true,
  maxContentSize: 10000
});

// ページネーションで検索する
await searchComponents({
  query: "button",
  page: 1,
  pageSize: 10
});

AIアシスタントの使用ヒント

Claudeや他のAIアシスタントで使用する場合：

1. 探索から始める：category: "all"でlist_componentsまたはquery: "*"でsearch_componentsを使用して、利用可能なすべてのコンポーネントを確認します。
2. ストーリーIDを取得する：他のツールに必要な正確なストーリーIDを見つけるには、get_component_variantsを使用します。
3. 正確なIDを使用する：ストーリーIDは "component-name--story-name" の形式（例："button--primary"）である必要があります。
4. 目的別に探索する：get_component_by_purposeを使用して、機能別にコンポーネントを検索します。
5. 問題をデバッグする：結果が見つからない場合、ツールにはデバッグ情報が含まれます。

📚 ドキュメント

詳細なセットアップ手順については、DEVELOPMENT.md を参照してください。

利用可能なツール

コアツール

1. list_components

   • Storybookインスタンスから利用可能なすべてのコンポーネントをリストします。
   • コンポーネントの名前、カテゴリ、および関連するストーリーを返します。
   • category: "all" を使用するか、カテゴリパラメータを省略してすべてのコンポーネントをリストします。
   • 特定のカテゴリパス（例："Components/Buttons"、"Layout"）でフィルタリングします。
   • page と pageSize パラメータでページネーションをサポートします（デフォルト：1ページあたり50件）。

2. get_component_html

   • Storybook内の特定のコンポーネントストーリーからHTMLを抽出します。
   • ストーリーIDの形式 "component-name--story-name" が必要です（例："button--primary"）。
   • 有効なストーリーIDを見つけるには、まず list_components または get_component_variants を使用します。
   • コンポーネントのスタイルを理解するために、オプションでCSSスタイルを抽出します。
   • 動的JavaScriptでレンダリングされたコンテンツをサポートします。

3. get_component_variants

   • 特定のコンポーネントのすべてのストーリーバリアント/状態を取得します。
   • コンポーネントのすべてのストーリー（バリアント）を、それらのID、名前、およびパラメータとともに返します。
   • コンポーネント名は、list_components で表示されるものと正確に一致する必要があります（大文字と小文字を区別）。

4. search_components

   • 名前、タイトル、またはカテゴリでコンポーネントを大文字小文字を区別せずに部分一致検索します。
   • 名前はコンポーネント名のみ（例："Button"）。
   • タイトルは完全なストーリーパス（例："Components/Forms/Button"）。
   • カテゴリはグループ化（例："Components/Forms"）。
   • query: "*" を使用してすべてのコンポーネントをリストします。
   • 特定のフィールド（"name"、"title"、"category"、または "all"（デフォルト））で検索します。
   • page と pageSize パラメータでページネーションをサポートします（デフォルト：1ページあたり50件）。

コンポーネント分析ツール

5. get_component_props

   • StorybookのargTypes構成からコンポーネントのプロパティ/APIドキュメントを抽出します。
   • プロパティ名、型、デフォルト値、必須状態、およびコントロールオプションを含みます。
   • ストーリーIDの形式 "component-name--story-name" が必要です。

6. get_component_dependencies

   • レンダリングされたHTMLを分析して、特定のコンポーネントが内部で使用している他のコンポーネントを見つけます。
   • Reactコンポーネント、ウェブコンポーネント、およびCSSクラスパターンを検出します。
   • コンポーネントの関係と構成を理解するのに役立ちます。
   • ストーリーIDの形式 "component-name--story-name" が必要です。

デザインシステムツール

7. get_layout_components

   • グリッド、コンテナ、スタック、ボックスなどのすべてのレイアウトコンポーネントを例とともに取得します。
   • 各レイアウトコンポーネントのオプションのHTML例。
   • ページ構造と構成パターンを理解するのに役立ちます。

8. get_theme_info

   • デザインシステムのテーマ情報（色、間隔、タイポグラフィ、ブレークポイント）を取得します。
   • デザインシステムからCSSカスタムプロパティ/変数を抽出します。
   • トークンをタイプ別に分類して整理します。
   • すべてのCSSカスタムプロパティを含めるには、includeAll: true を使用します。

探索ツール

9. get_component_by_purpose

   • 目的または機能別にコンポーネントを検索します。
   • 利用可能な目的："form inputs"（入力フィールド、セレクト、チェックボックス）、"navigation"（メニュー、パンくずリスト、タブ）、"feedback"（アラート、トースト、モーダル）、"data display"（テーブル、カード、リスト）、"layout"（グリッド、コンテナ、デバイダー）、"buttons"（すべてのボタンタイプ）、"progress"（ローダー、スピナー）、"media"（画像、ビデオ、カルーセル）。
   • ユースケース別にコンポーネントを見つけるための柔軟なパターンマッチング。
   • page と pageSize パラメータでページネーションをサポートします（デフォルト：1ページあたり50件）。

10. get_component_composition_examples

    • 実際のパターンやレイアウトでコンポーネントがどのように組み合わされるかの例を取得します。
    • フォーム、カード、レイアウト、または複雑なUIパターンで他のコンポーネントとともに使用されるコンポーネントを示すHTML例を返します。
    • コンポーネントが実際にどのように連携するかを理解するのに役立ちます。
    • 返される例の数を制御するためのオプションの制限パラメータ。

11. get_external_css ⚠️ TOKEN-OPTIMIZED

    • デフォルト：デザイントークン + ファイル統計のみを返します（トークン制限を回避）。
    • デフォルトでは CSSコンテンツを返しません（25Kトークン制限エラーを防止）。
    • トークンを抽出して分類します：色、間隔、タイポグラフィ、影、ブレークポイント。
    • CSSコンテンツが特に必要な場合のみ、includeFullCSS: true を使用します。
    • セキュリティ保護されています：Storybookと同じドメインのURLのみを受け入れます。
    • レスポンスサイズ制限に達することなくデザイントークンを抽出するのに最適

動作原理

/index.json と /iframe.html エンドポイントを介してStorybookに接続します。ヘッドレスChromeでPuppeteerを使用して、動的JavaScriptのレンダリングを行います。スマートキャッシュとタイムアウト保護を備えたコンポーネントのHTML、スタイル、プロパティ、依存関係、およびデザイントークンを抽出します。

トラブルシューティング

• Storybookが実行されていることと、STORYBOOK_URL が正しいことを確認します。
• 正確なストーリーIDの形式 "component-name--story-name" を使用します。
• まず list_components を使用して、利用可能なコンポーネントを確認します。
• ブラウザで直接 /index.json エンドポイントを確認します。
• 詳細なトラブルシューティングについては、DEVELOPMENT.md を参照してください。

必要条件

• Node.js 18以上
• Chrome/Chromium（Puppeteer用）
• 実行中のStorybookインスタンス

開発

詳細な開発手順については、DEVELOPMENT.md を参照してください。

📄 ライセンス

MIT