mcp-design-system-extractor

MCP Design System Extractor

Storybook デザインシステムからコンポーネント情報を抽出する Model Context Protocol（MCP）サーバーです。Storybook インスタンスに接続し、HTML、スタイル、コンポーネントのメタデータを抽出します。

インストール

Claude CLI を使用する（推奨）

claude mcp add design-system npx mcp-design-system-extractor@latest \
  --env STORYBOOK_URL=http://localhost:6006

自己署名証明書を使用する場合：

claude mcp add design-system npx mcp-design-system-extractor@latest \
  --env STORYBOOK_URL=https://my-storybook.example.com \
  --env NODE_TLS_REJECT_UNAUTHORIZED=0

npm を使用する

npm install -g mcp-design-system-extractor

その後、MCP クライアントで設定します（環境変数を参照）。

ソースから

git clone https://github.com/freema/mcp-design-system-extractor.git
cd mcp-design-system-extractor
npm install && npm run build
npm run setup  # Interactive setup for Claude Desktop

主な依存関係

• Puppeteer：動的な JavaScript コンポーネントのレンダリングにヘッドレス Chrome を使用します
• Chrome/Chromium：Puppeteer に必要です（Docker では自動的に処理されます）
• ビルド済みの Storybook ディストリビューションで動作します

機能

• コンポーネント一覧：Storybook で利用可能なすべてのコンポーネントをコンパクトモードで取得します
• HTML の抽出：任意のコンポーネントのレンダリング済み HTML を取得します（非同期または同期モード）
• コンポーネントの検索：名前、タイトル、カテゴリ、目的でコンポーネントを検索します
• コンポーネントの依存関係：ほかのコンポーネント内で使用されているコンポーネントを分析します
• テーマ情報：デザインシステムのテーマ（色、スペーシング、タイポグラフィ）を抽出します
• 外部 CSS の分析：CSS ファイルを取得・分析してデザイントークンを抽出します
• 非同期ジョブキュー：時間のかかる処理をバックグラウンドで実行し、ジョブを追跡します

環境変数

変数	説明	デフォルト
STORYBOOK_URL	Storybook インスタンスの URL	http://localhost:6006
NODE_TLS_REJECT_UNAUTHORIZED	0 に設定すると SSL 証明書の検証をスキップします（自己署名証明書の場合）	1

自己署名証明書を使用する場合の例：

{
  "mcpServers": {
    "design-system": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "STORYBOOK_URL": "https://my-storybook.example.com",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

使用方法

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

利用可能なツール（全 9 種類）

コアツール

1. list_components

   • Storybook インスタンスで利用可能なすべてのコンポーネントを一覧表示します
   • 最小限の出力にするには compact: true を使用します（応答サイズを削減します）
   • category パラメーターで絞り込みます
   • page と pageSize によるページネーションに対応しています（デフォルト：20）

2. get_component_html

   • 特定のコンポーネントストーリーから HTML を抽出します
   • デフォルトでは非同期：job_id を返します。結果を取得するには job_status を使用します
   • 同期モードにするには async: false を設定します（timeout パラメーターを使用します）
   • 利用可能なバリアントの一覧を取得するには variantsOnly: true を使用します（同期、高速）
   • CSS を抽出するには includeStyles: true を指定します（Storybook の CSS は除外されます）
   • ストーリー ID の形式："component-name--story-name"、または "component-name" のみ（デフォルトのバリアントに自動解決されます）

3. search_components

   • 名前、タイトル、カテゴリ、目的でコンポーネントを検索します
   • query：検索語（すべてを対象にするには "*" を使用します）
   • purpose：機能で検索します（"form inputs"、"navigation"、"feedback"、"buttons" など）
   • searchIn："name"、"title"、"category"、または "all"（デフォルト）
   • page と pageSize によるページネーションに対応しています

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

4. get_component_dependencies
   • レンダリング済み HTML を分析し、内部で使用されているほかのコンポーネントを特定します
   • React コンポーネント、Web コンポーネント、CSS クラスのパターンを検出します
   • ストーリー ID は "component-name--story-name" の形式で指定する必要があります

デザインシステムツール

5. get_theme_info

   • デザインシステムのテーマ（色、スペーシング、タイポグラフィ、ブレークポイント）を抽出します
   • CSS カスタムプロパティ／変数を取得します
   • すべての CSS 変数を取得するには includeAll: true を使用します

6. get_external_css

   • デフォルト：デザイントークンとファイル統計のみを返します（トークン制限を回避します）
   • 色、スペーシング、タイポグラフィ、シャドウのトークンを抽出・分類します
   • CSS 全体の内容が必要な場合に限り includeFullCSS: true を使用します
   • セキュリティ保護：Storybook と同じドメインの URL のみ受け付けます

ジョブ管理ツール

7. job_status

   • 非同期ジョブのステータスを確認します
   • 返される値：status、result（完了時）、error（失敗時）
   • 非同期モードで get_component_html を呼び出した後にポーリングします

8. job_cancel

   • キューに登録されたジョブまたは実行中のジョブをキャンセルします
   • キャンセルに成功したかどうかを返します

9. job_list

   • すべてのジョブとそのステータスを一覧表示します
   • status でフィルタリングします：「all」（デフォルト）、「active」（キュー登録済み／実行中）、「completed」
   • ジョブ一覧とキューの統計情報を返します

使用例

// List all components (compact mode recommended)
await list_components({ compact: true });

// Search for components
await search_components({ query: "button", searchIn: "name" });

// Find components by purpose
await search_components({ purpose: "form inputs" });

// Get variants for a component
await get_component_html({
  componentId: "button",
  variantsOnly: true
});
// Returns: { variants: ["primary", "secondary", "disabled"] }

// Get HTML (async mode - default)
await get_component_html({ componentId: "button--primary" });
// Returns: { job_id: "job_xxx", status: "queued" }

// Poll for result
await job_status({ job_id: "job_xxx" });
// Returns: { status: "completed", result: { html: "...", classes: [...] } }

// Get HTML (sync mode)
await get_component_html({
  componentId: "button--primary",
  async: false,
  timeout: 30000
});
// Returns: { html: "...", classes: [...] }

// Get HTML with styles
await get_component_html({
  componentId: "button--primary",
  async: false,
  includeStyles: true
});

// Check all running jobs
await job_list({ status: "active" });

// Extract theme info
await get_theme_info({ includeAll: false });

// Get design tokens from CSS
await get_external_css({
  cssUrl: "https://my-storybook.com/assets/main.css"
});

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

1. まず検出する：compact: true を指定して list_components を使用します
2. 先にバリアントを取得する：variantsOnly: true を指定して get_component_html を使用します
3. HTML の取得には非同期モードを使用する：デフォルトの非同期モードにより、大規模なコンポーネントでのタイムアウトを防げます
4. job_status をポーリングする：結果を読み取る前にジョブの完了を確認します
5. 目的で検索する：purpose パラメーターを指定して search_components を使用します

プロンプトの例

接続後、Claude に自然言語のプロンプトを使用できます：

コンポーネントの検出：

Show me all available button components in the design system

新機能の構築：

I need to create a user profile card. Find relevant components
from the design system and show me their HTML structure.

デザインシステムの分析：

Extract the color palette and typography tokens from the design system.
I want to ensure my new component matches the existing styles.

コンポーネントの移行：

Get the HTML and styles for the "alert" component. I need to
recreate it in a different framework while keeping the same look.

複数ツールのワークフロー：

First list all form-related components, then get the HTML for
the input and select components. I'm building a registration form.

仕組み

/index.json および /iframe.html エンドポイント経由で Storybook に接続します。動的な JavaScript のレンダリングには、ヘッドレス Chrome と Puppeteer を使用します。長時間実行される処理には、同時実行ジョブ数を最大 2 件とし、完了したジョブの TTL を 1 時間とするインメモリのジョブキューを使用します。

トラブルシューティング

• Storybook が実行中であり、STORYBOOK_URL が正しいことを確認してください
• まず list_components を使用して、利用可能なコンポーネントを確認してください
• 大規模なコンポーネントでは、非同期モード（デフォルト）を使用して job_status をポーリングしてください
• ブラウザーで /index.json エンドポイントを直接確認してください
• SSL 証明書エラー：自己署名証明書の場合は NODE_TLS_REJECT_UNAUTHORIZED=0 を設定してください
• 詳しいトラブルシューティングについては、DEVELOPMENT.md を参照してください

要件

• Node.js 20+
• Chrome/Chromium（Puppeteer 用）
• 実行中の Storybook インスタンス（対応バージョンについては以下を参照）

対応する Storybook のバージョン

Storybook 7、8、9、10。 サーバーはストーリーインデックスを /index.json から読み込み、利用できない場合は /stories.json にフォールバックします。また、 /iframe.html?id=<storyId> 経由でストーリーをレンダリングします。これらのエンドポイントは、 4 つのメジャーバージョンすべてで安定して利用できます。

Storybook 6 以前は、/index.json より前のバージョンであり、 異なるストーリー ID の方式を使用しているため、サポートされていません。

開発サーバー（npm run storybook）と、HTTP 経由で配信されるビルド済みの静的 Storybook のどちらも利用できます。

開発

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

作者

Tomáš Grasl によって作成されました

ライセンス

MIT