Storybook MCP

[!TIP] このリポジトリは、Storybook v10.6.0 以降、storybookjs/storybook に移転しました。最新のドキュメントはそちらを参照してください。

---

Storybook MCP

Storybook MCP Addon モノレポへようこそ！このプロジェクトは、UI コンポーネント情報と開発ワークフローを公開する MCP（Model Context Protocol）サーバーを提供することで、AI エージェントが Storybook をより効率的に操作できるようにします。

📦 パッケージ

このモノレポには、4 つの主要なパッケージが含まれています：

• @storybook/mcp - Storybook コンポーネントの知識を提供するためのスタンドアロン MCP ライブラリ（単独で使用可能）
• @storybook/addon-mcp - Storybook 開発サーバー内で MCP サーバーを実行する Storybook アドオンで、ローカルの Storybook から @storybook/mcp の機能を含みます
• @storybook/claude-code-plugin - Storybook セットアップスキルと MCP 設定を備えた Claude Code プラグイン
• @storybook/codex-plugin - Storybook セットアップスキルと MCP 設定を備えた Codex プラグイン

各パッケージには、ユーザー向けのドキュメントが記載された独自の README があります。このドキュメントは、これらのパッケージの開発、テスト、または貢献を目的としたコントリビューター向けです。

🚀 クイックスタート

GitHub から Claude および Codex プラグインをテストする

外部テスターは、このリポジトリの main ブランチから直接プラグインマーケットプレイスをインストールできます。ローカルクローンは不要です。

Codex（詳細）

codex plugin marketplace add storybookjs/mcp --ref main
codex plugin add storybook@storybook

マーケットプレイスとプラグインを確認します：

codex plugin marketplace list
codex plugin list --marketplace storybook

Claude Code（詳細）

claude plugin marketplace add storybookjs/mcp@main --scope user
claude plugin install storybook@storybook --scope user

プラグインと MCP サーバーを確認します：

claude plugin list --json
claude mcp list

このリポジトリは、マーケットプレイスカタログを意図的に 2 か所に保持しています。ルートのカタログは storybookjs/mcp からの GitHub インストールをサポートし、パッケージローカルのカタログはローカルパッケージ開発スクリプトをサポートします。相対的なプラグインソースパスを除いて同一に保つ必要があり、パッケージの検証チェックでそれが確認されます。

前提条件

• Node.js 24+ - このプロジェクトには Node.js 24 以降が必要です（.nvmrc を参照）
• pnpm 10.19.0+ - 厳格なパッケージマネージャー要件（package.json で強制）

# Use the correct Node version
nvm use

# Install pnpm if you don't have it
npm install -g pnpm@10.19.0

インストール

# Clone the repository
git clone https://github.com/storybookjs/mcp.git
cd addon-mcp

# Install all dependencies (for all packages in the monorepo)
pnpm install

開発ワークフロー

# Build all packages
pnpm build

# Start development mode (watches for changes in all packages)
pnpm dev

# Run unit tests in watch mode
pnpm test

# Run unit tests once
pnpm test:run

# Run Storybook with the addon for testing
pnpm --filter internal-storybook storybook

Storybook コマンドは以下を起動します：

• http://localhost:6006 の内部テスト用 Storybook インスタンス
• 変更が自動的に反映されるウォッチモードのアドオン
• http://localhost:6006/mcp で利用可能な MCP サーバー

🛠️ 一般的なタスク

開発

turbo watch build コマンドはすべてのパッケージをウォッチモードで実行し、変更時に自動的に再ビルドします：

# Start development mode for all packages
pnpm turbo watch build

# This is usually all you need - starts Storybook AND watches addon for changes
pnpm storybook

ビルド

# Build all packages
pnpm build

テスト

モノレポはルートレベルで集中化された Vitest 設定を使用し、各パッケージ用にプロジェクトが設定されています：

# Watch tests across all packages
pnpm test

# Run tests once across all packages
pnpm test:run

# Run tests with coverage and CI reporters
pnpm test:ci

MCP サーバーのデバッグ

MCP Inspector を使用して、MCP サーバーの機能をデバッグおよびテストします：

# Launches the MCP inspector (requires Storybook to be running)
pnpm inspect

これは .mcp.inspect.json の設定を使用して、ローカルの MCP サーバーに接続します。

または、以下の curl コマンドを使用して、すべてが正常に動作することを確認することもできます：

# test that the mcp server is running
# use port 6006 to test the addon-mcp server instead
curl -X POST \
  http://localhost:13316/mcp      \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# test a specific tool call
curl -X POST http://localhost:13316/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list-all-documentation",
      "arguments": {}
    }
  }'

Storybook でのデバッグ

Storybook を以下のコマンドで起動できます：

pnpm storybook

これにより、すべてがビルドされ、addon-mcp を使用して Storybook が起動します。その後、コーディングエージェントを http://localhost:6006/mcp（または設定したアドオンエンドポイント）に接続して試すことができます。

MCP アプリの操作

preview-stories ツールの一部としてレンダリングされる MCP アプリを操作およびデバッグするには、次の手順を実行します：

1. VSCode の Insiders ビルドを使用する
2. chat.mcp.apps.enabled 設定が有効になっていることを確認する
3. ルートで pnpm storybook を実行して、リポジトリの Storybook をウォッチモードで起動する
4. VSCode を再起動し、.vscode/mcp.json ファイルを開いて、Storybook MCP が「実行中」と表示されていることを確認します。表示されていない場合は「開始」をクリックします。
5. VSCode でチャットを開き、次のようなプロンプトを書きます：

Storybook MCP を使用して、すべてのボタンストーリーの外観を表示してください

6. この最初のプロンプトの後、変更を行うたびに Storybook が自動的に再起動します。完全に準備ができるまで待ってから、「ツールを再度実行」とプロンプトを入力します。

また、MCPJam のインスペクター を使用して、ツール呼び出しをより低レベルで制御することもできます。

フォーマットとリンティング

# Format all files with Prettier
pnpm format

# Check formatting without changing files
pnpm format:check

# Lint code with oxlint
pnpm lint

# Lint with GitHub Actions format (for CI)
pnpm lint:ci

# Check package exports with publint
pnpm publint

🔍 品質チェック

モノレポには、CI で実行されるいくつかの品質チェックが含まれています：

# Run all checks (build, test, lint, format, typecheck, publint)
pnpm check

# Run checks in watch mode (experimental)
pnpm check:watch

# Type checking (uses tsc directly, not turbo)
pnpm typecheck

# Type checking with turbo (for individual packages)
pnpm turbo:typecheck

# Testing with turbo (for individual packages)
pnpm turbo:test

📝 コード規約

TypeScript とインポート

相対インポートには常にファイル拡張子を含めます：

// ✅ Correct
import { foo } from './bar.ts';

// ❌ Wrong
import { foo } from './bar';

• JSON インポートは import 属性構文を使用します：

import pkg from '../package.json' with { type: 'json' };

🚢 リリースプロセス

このプロジェクトはバージョン管理に Changesets を使用しています：

# 1. Create a changeset describing your changes
pnpm changeset

PR を作成する際、変更がリリースをトリガーする場合は changeset を追加してください：

• Patch：バグ修正、ドキュメント更新
• Minor：新機能、後方互換性のある変更
• Major：破壊的な変更

🤝 貢献

貢献を歓迎します！始める方法は次のとおりです：

1. リポジトリをフォークし、フィーチャーブランチを作成します
2. 上記のコード規約に従って変更を加えます
3. 内部の Storybook インスタンスを使用して変更をテストします
4. 変更がリリースに値する場合はchangeset を作成します
5. 明確な説明を添えてプルリクエストを送信します

提出前の確認

• コードがエラーなくビルドされる（pnpm build）
• テストがパスする（pnpm test:run）
• コードがフォーマットされている（pnpm format）
• コードがリントされている（pnpm lint）
• 型チェックがパスする（pnpm typecheck）
• MCP インスペクターまたは内部 Storybook で変更がテストされている
• 必要に応じて changeset が作成されている（pnpm changeset）

ヘルプの入手

• アイデアと機能リクエスト：ディスカッションを開始
• バグ報告：イシューを開く
• 質問：GitHub Discussions で質問する

📄 ライセンス

MIT - 詳細は LICENSE を参照

---

注：このプロジェクトは実験的であり、活発に開発中です。AI エージェントと Storybook を統合する最良の方法を模索するにつれて、API とアーキテクチャは変更される可能性があります。