storybook-mcp-integration

Storybook MCP Integration

Storybook MCP サーバー（@storybook/addon-mcp）を使うと、エージェントがプロジェクトの実際のコンポーネントライブラリ（props、ストーリー、テスト、ライブプレビュー）を把握できます。

使用するタイミング

• コンポーネント生成 — 新しいコンポーネントを作成する前に、既存の Storybook コンポーネントを確認します
• コンポーネントテスト — CLI の代わりに MCP 経由でストーリーテストと a11y 監査を実行します
• ビジュアル検証 — チャットにストーリープレビューを埋め込んで、ユーザーに確認してもらいます
• コンポーネント監査 — MCP 経由で完全なメタデータを含むコンポーネント一覧を取得します

クイックリファレンス — 6 つのツール、3 つのツールセット

ツールセット	ツール	用途	主な入力
dev	get-storybook-story-instructions	ストーリーとインタラクションテストの作成方法に関するガイダンス	なし
dev	preview-stories	ストーリーのプレビュー URL を返します（埋め込み可能）	stories[]: {storyId} または {absoluteStoryPath, exportName}
docs	list-all-documentation	コンポーネントとドキュメントの完全なマニフェストインデックス	なし
docs	get-documentation	props、最初の 3 つのストーリー、ストーリーインデックス、ドキュメント	id（必須）、storybookId（任意）
docs	get-documentation-for-story	ストーリーのソース全体とコンポーネントのドキュメント	componentId、storyName（必須）
testing	run-story-tests	コンポーネントテストと a11y テストを実行し、合否と違反を返します	stories[]（任意）、a11y ブール値（デフォルトは true）

前提条件

# Storybook 10.3+ with Vite builder (no webpack)
npx storybook@latest upgrade

# Install the addon (current: @storybook/[email protected], Apr 2026)
npx storybook add @storybook/addon-mcp

# Enable docs toolset (required for component discovery)
# In .storybook/main.ts:
#   componentsManifest: true
# NOTE: the old `experimentalComponentsManifest` flag was renamed in
# Storybook 10.3; it is now `componentsManifest` and default-on. Any
# code still passing the `experimental` prefix will warn-then-ignore.

# For Chromatic remote setups, use the standalone package instead of
# the addon (same tool surface, no local Storybook required):
#   npm i -D @storybook/mcp
#   npx storybook-mcp --registry https://chromatic.storybook.cloud

# Enable testing toolset (requires addon-vitest)
# npx storybook add @storybook/addon-vitest

# Register with Claude Code
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project

検出パターン

Storybook MCP ツールを使用する前に、利用可能かどうかを確認します。

# Probe for storybook-mcp tools
ToolSearch(query="+storybook list-all-documentation")

# If tools found → Storybook MCP is available
# If not found → fallback to filesystem-based component discovery

ルールの詳細

Read("rules/<file>") で必要に応じてルールを読み込みます。

ルール	影響度	説明
component-discovery	HIGH	新しいコンポーネントを生成する前に、list-all-documentation と get-documentation を使用します
story-preview-verification	HIGH	ビジュアル確認のために preview-stories の URL を埋め込みます
mcp-test-runner	CRITICAL	コンポーネントの生成後、a11y:true を指定して run-story-tests を実行します

ツールセットの選択

X-MCP-Toolsets ヘッダーでツールセットを絞り込み、エージェントのコンテキストを削減します。

エージェントの役割	ツールセット	理由
component-curator	docs	一覧と props のみ。テストは行いません
frontend-ui-developer	dev,docs,testing	生成から検証までのサイクルに必要なすべての機能を利用できます
design-system-architect	docs	ガバナンス向けのコンポーネントメタデータ

Chromatic リモート公開

Chromatic を使用しているチームは、docs ツールセットをリモートで公開できます。

• https://<chromatic-storybook-url>/mcp で公開されます
• リモートで利用できるのは docs ツールセットのみです（dev と testing にはローカルの Storybook が必要です）
• Storybook をローカルで実行せずに、チーム間でデザインシステムを調べるのに便利です

フォールバック

Storybook MCP	フォールバック	動作
利用可能	—	コンポーネントの検索、テスト、プレビューに MCP ツールを使用します
利用不可	ファイルシステム	Glob("**/components/**/*.tsx") と Grep でコンポーネント一覧を取得します
利用不可	21st.dev	21st-dev-magic MCP 経由で公開レジストリを検索します
利用不可	手動	Claude のマルチモーダル分析でスクリーンショットを解析します

関連スキル

• storybook-testing — CSF3 パターン、Vitest 統合、Chromatic TurboSnap
• component-search — 21st.dev レジストリ検索（外部コンポーネント）
• design-to-code — モックアップからコンポーネントまでの完全なパイプライン（ステージ 2 でこのスキルを使用）
• ui-components — shadcn/ui と Radix のコンポーネントパターン