Storybook MCP

Storybook MCP - คู่มือสำหรับผู้มีส่วนร่วม

ยินดีต้อนรับสู่ monorepo ของ Storybook MCP Addon! โปรเจกต์นี้ช่วยให้ AI agent ทำงานกับ Storybook ได้อย่างมีประสิทธิภาพมากขึ้น โดยการให้บริการเซิร์ฟเวอร์ MCP (Model Context Protocol) ที่เปิดเผยข้อมูล UI component และขั้นตอนการทำงานในการพัฒนา

📦 แพ็คเกจ

monorepo นี้ประกอบด้วยแพ็คเกจหลักสี่แพ็คเกจ:

• @storybook/mcp - ไลบรารี MCP แบบสแตนด์อโลนสำหรับให้บริการความรู้เกี่ยวกับ Storybook component (สามารถใช้แยกต่างหากได้)
• @storybook/addon-mcp - addon ของ Storybook ที่รันเซิร์ฟเวอร์ MCP ภายในเซิร์ฟเวอร์ dev ของ Storybook และรวมฟังก์ชันการทำงานของ @storybook/mcp จาก Storybook ในเครื่องของคุณ
• @storybook/claude-code-plugin - ปลั๊กอิน Claude Code พร้อมทักษะการตั้งค่า Storybook และการกำหนดค่า MCP
• @storybook/codex-plugin - ปลั๊กอิน Codex พร้อมทักษะการตั้งค่า Storybook และการกำหนดค่า MCP

แต่ละแพ็คเกจมี README ของตัวเองพร้อมเอกสารที่面向ผู้ใช้ เอกสารนี้สำหรับ ผู้มีส่วนร่วม ที่ต้องการพัฒนา ทดสอบ หรือมีส่วนร่วมกับแพ็คเกจเหล่านี้

🚀 เริ่มต้นอย่างรวดเร็ว

การทดสอบปลั๊กอิน Claude และ Codex จาก GitHub

ผู้ทดสอบภายนอกสามารถติดตั้ง marketplace ของปลั๊กอินได้โดยตรงจาก branch main ของ repository นี้ ไม่จำเป็นต้อง clone ในเครื่อง

Codex (รายละเอียดเพิ่มเติม)

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

ตรวจสอบ marketplace และปลั๊กอิน:

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

repository จงใจเก็บแคตตาล็อก marketplace ไว้สองที่ แคตตาล็อกที่ root รองรับการติดตั้งจาก GitHub จาก storybookjs/mcp; แคตตาล็อกเฉพาะแพ็คเกจ รองรับสคริปต์การพัฒนาแพ็คเกจในเครื่อง ทั้งสองควรเหมือนกัน ยกเว้นพาธต้นทางของปลั๊กอินแบบสัมพัทธ์ และการตรวจสอบแพ็คเกจจะตรวจสอบว่าเป็นเช่นนั้น

ข้อกำหนดเบื้องต้น

• 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 เริ่มต้น:

• อินสแตนซ์ Storybook ทดสอบภายในที่ http://localhost:6006
• addon ในโหมด watch เพื่อให้การเปลี่ยนแปลงสะท้อนโดยอัตโนมัติ
• เซิร์ฟเวอร์ MCP พร้อมใช้งานที่ http://localhost:6006/mcp

🛠️ งานทั่วไป

การพัฒนา

คำสั่ง turbo watch build รันแพ็คเกจทั้งหมดในโหมด watch สร้างใหม่โดยอัตโนมัติเมื่อคุณทำการเปลี่ยนแปลง:

# 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

การทดสอบ

monorepo ใช้การกำหนดค่า Vitest แบบรวมศูนย์ที่ระดับ root พร้อมโปรเจกต์ที่กำหนดค่าสำหรับแต่ละแพ็คเกจ:

# 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

สิ่งนี้จะสร้างทุกอย่างและเริ่ม Storybook พร้อม addon-mcp จากนั้นคุณสามารถเชื่อมต่อ coding agent ของคุณไปที่ http://localhost:6006/mcp (หรือปลายทาง addon ที่คุณกำหนดค่าไว้) และลองใช้งาน

การทำงานกับ MCP App

ในการทำงานและดีบัก MCP app ที่แสดงผลเป็นส่วนหนึ่งของเครื่องมือ preview-stories คุณสามารถ:

1. ใช้ VSCode รุ่น Insiders
2. ตรวจสอบว่าเปิดใช้งานการตั้งค่า chat.mcp.apps.enabled แล้ว
3. เริ่ม Storybook ของ repo ในโหมด watch โดยรัน pnpm storybook ใน root
4. รีสตาร์ท VSCode และเปิดไฟล์ .vscode/mcp.json และตรวจสอบว่า Storybook MCP ถูกทำเครื่องหมายเป็น Running มิฉะนั้นให้คลิก Start
5. เปิดแชทใน VSCode และเขียนพรอมต์เช่นนี้:

แสดงให้ฉันดูว่าเรื่องราวของปุ่มทั้งหมดมีลักษณะอย่างไร โดยใช้ Storybook MCP

6. หลังจากพรอมต์แรกนี้ เมื่อใดก็ตามที่คุณทำการเปลี่ยนแปลง Storybook จะรีสตาร์ทโดยอัตโนมัติ รอให้พร้อมเต็มที่ จากนั้นคุณสามารถพรอมต์ "รันเครื่องมืออีกครั้ง"

คุณยังสามารถใช้ inspector จาก 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

🔍 การตรวจสอบคุณภาพ

monorepo รวมการตรวจสอบคุณภาพหลายอย่างที่ทำงานใน 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 attributes:

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

🚢 กระบวนการเผยแพร่

โปรเจกต์นี้ใช้ Changesets สำหรับการจัดการเวอร์ชัน:

# 1. Create a changeset describing your changes
pnpm changeset

เมื่อคุณสร้าง PR ให้เพิ่ม changeset หากการเปลี่ยนแปลงของคุณควรทริกเกอร์การเผยแพร่:

• Patch: การแก้ไขข้อบกพร่อง การอัปเดตเอกสาร
• Minor: ฟีเจอร์ใหม่ การเปลี่ยนแปลงที่เข้ากันได้แบบย้อนหลัง
• Major: การเปลี่ยนแปลงที่ทำลายความเข้ากันได้

🤝 การมีส่วนร่วม

เรายินดีรับการมีส่วนร่วม! นี่คือวิธีการเริ่มต้น:

1. Fork repository และสร้าง branch ฟีเจอร์
2. ทำการเปลี่ยนแปลงของคุณ ตามข้อตกลงเกี่ยวกับโค้ดข้างต้น
3. ทดสอบการเปลี่ยนแปลงของคุณ โดยใช้อินสแตนซ์ Storybook ภายใน
4. สร้าง changeset หากการเปลี่ยนแปลงของคุณสมควรได้รับการเผยแพร่
5. ส่ง pull request พร้อมคำอธิบายที่ชัดเจน

ก่อนส่ง

• โค้ดสร้างได้โดยไม่มีข้อผิดพลาด (pnpm build)
• การทดสอบผ่าน (pnpm test:run)
• โค้ดได้รับการจัดรูปแบบ (pnpm format)
• โค้ดผ่านการตรวจสอบ (pnpm lint)
• การตรวจสอบประเภทผ่าน (pnpm typecheck)
• การเปลี่ยนแปลงทดสอบด้วย MCP inspector หรือ Storybook ภายใน
• สร้าง changeset หากจำเป็น (pnpm changeset)

การขอความช่วยเหลือ

• ไอเดีย & คำขอฟีเจอร์: เริ่มการสนทนา
• รายงานข้อบกพร่อง: เปิด issue
• คำถาม: ถามใน GitHub Discussions

📄 ใบอนุญาต

MIT - ดู LICENSE สำหรับรายละเอียด

---

หมายเหตุ: โปรเจกต์นี้เป็นการทดลองและอยู่ระหว่างการพัฒนาอย่างต่อเนื่อง API และสถาปัตยกรรมอาจเปลี่ยนแปลงได้ในขณะที่เราสำรวจวิธีที่ดีที่สุดในการผสานรวม AI agent กับ Storybook