Storybook MCP

[!TIP] Kho lưu trữ này đã được chuyển đến storybookjs/storybook kể từ Storybook v10.6.0. Vui lòng kiểm tra tại đó để xem tài liệu cập nhật.

---

Storybook MCP

Chào mừng bạn đến với monorepo Storybook MCP Addon! Dự án này cho phép các tác nhân AI làm việc hiệu quả hơn với Storybook bằng cách cung cấp một máy chủ MCP (Model Context Protocol) hiển thị thông tin thành phần giao diện người dùng và các quy trình phát triển.

📦 Các gói

Monorepo này chứa bốn gói chính:

• @storybook/mcp - Thư viện MCP độc lập để phục vụ kiến thức thành phần Storybook (có thể sử dụng độc lập)
• @storybook/addon-mcp - Addon Storybook chạy máy chủ MCP trong máy chủ phát triển Storybook của bạn và bao gồm chức năng của @storybook/mcp từ Storybook cục bộ của bạn
• @storybook/claude-code-plugin - Plugin Claude Code với các kỹ năng thiết lập Storybook và cấu hình MCP
• @storybook/codex-plugin - Plugin Codex với các kỹ năng thiết lập Storybook và cấu hình MCP

Mỗi gói có README riêng với tài liệu hướng đến người dùng. Tài liệu này dành cho những người đóng góp muốn phát triển, kiểm thử hoặc đóng góp cho các gói này.

🚀 Bắt đầu nhanh

Kiểm thử plugin Claude và Codex từ GitHub

Người kiểm thử bên ngoài có thể cài đặt marketplace plugin trực tiếp từ nhánh main của kho lưu trữ này. Không cần sao chép cục bộ.

Codex (chi tiết hơn)

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

Xác minh marketplace và plugin:

codex plugin marketplace list
codex plugin list --marketplace storybook

Claude Code (chi tiết hơn)

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

Xác minh plugin và máy chủ MCP:

claude plugin list --json
claude mcp list

Kho lưu trữ cố ý giữ các danh mục marketplace ở hai nơi. Các danh mục gốc hỗ trợ cài đặt GitHub từ storybookjs/mcp; các danh mục cục bộ của gói hỗ trợ các tập lệnh phát triển gói cục bộ. Chúng nên giữ nguyên giống nhau ngoại trừ đường dẫn nguồn plugin tương đối và quá trình xác thực gói sẽ kiểm tra điều đó.

Điều kiện tiên quyết

• Node.js 24+ - Dự án yêu cầu Node.js 24 trở lên (xem .nvmrc)
• pnpm 10.19.0+ - Yêu cầu nghiêm ngặt về trình quản lý gói (được thực thi trong package.json)

# Use the correct Node version
nvm use

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

Cài đặt

# 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

Quy trình phát triển

# 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

Lệnh Storybook khởi động:

• Phiên bản Storybook kiểm thử nội bộ trên http://localhost:6006
• Addon ở chế độ theo dõi, để các thay đổi được phản ánh tự động
• Máy chủ MCP khả dụng tại http://localhost:6006/mcp

🛠️ Các tác vụ phổ biến

Phát triển

Lệnh turbo watch build chạy tất cả các gói ở chế độ theo dõi, tự động xây dựng lại khi bạn thực hiện thay đổi:

# 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

Xây dựng

# Build all packages
pnpm build

Kiểm thử

Monorepo sử dụng cấu hình Vitest tập trung ở cấp gốc với các dự án được cấu hình cho từng gói:

# 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

Gỡ lỗi máy chủ MCP

Sử dụng MCP Inspector để gỡ lỗi và kiểm thử chức năng máy chủ MCP:

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

Điều này sử dụng cấu hình trong .mcp.inspect.json để kết nối với các máy chủ MCP cục bộ của bạn.

Ngoài ra, bạn cũng có thể sử dụng các lệnh curl này để kiểm tra mọi thứ hoạt động:

# 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": {}
    }
  }'

Gỡ lỗi với Storybook

Bạn có thể khởi động Storybook bằng:

pnpm storybook

Điều này sẽ xây dựng mọi thứ và khởi động Storybook với addon-mcp, sau đó bạn có thể kết nối tác nhân mã hóa của mình tại http://localhost:6006/mcp (hoặc điểm cuối addon đã cấu hình của bạn) và thử nghiệm.

Làm việc với ứng dụng MCP

Để làm việc và gỡ lỗi ứng dụng MCP được hiển thị như một phần của công cụ preview-stories, bạn có thể:

1. Sử dụng bản dựng Insiders của VSCode
2. Đảm bảo cài đặt chat.mcp.apps.enabled được bật
3. Khởi động Storybook của kho lưu trữ ở chế độ theo dõi bằng cách chạy pnpm storybook trong thư mục gốc
4. Khởi động lại VSCode và mở tệp .vscode/mcp.json và đảm bảo Storybook MCP được đánh dấu là Đang chạy, nếu không hãy nhấp vào Bắt đầu.
5. Mở cuộc trò chuyện trong VSCode và viết lời nhắc như thế này:

Hiển thị cho tôi cách tất cả các câu chuyện nút trông như thế nào, sử dụng Storybook MCP

6. Sau lời nhắc đầu tiên này, bất cứ khi nào bạn thực hiện thay đổi, Storybook sẽ tự động khởi động lại. Đợi cho đến khi nó sẵn sàng hoàn toàn, sau đó bạn có thể nhắc "Chạy lại công cụ".

Bạn cũng có thể sử dụng trình kiểm tra từ MCPJam để có quyền kiểm soát cấp thấp hơn đối với các lệnh gọi công cụ.

Định dạng & Linting

# 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

🔍 Kiểm tra chất lượng

Monorepo bao gồm một số kiểm tra chất lượng chạy trong 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

📝 Quy ước mã

TypeScript & Nhập khẩu

Luôn bao gồm phần mở rộng tệp trong các nhập khẩu tương đối:

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

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

• Nhập khẩu JSON sử dụng cú pháp thuộc tính nhập khẩu:

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

🚢 Quy trình phát hành

Dự án này sử dụng Changesets để quản lý phiên bản:

# 1. Create a changeset describing your changes
pnpm changeset

Khi bạn tạo PR, hãy thêm changeset nếu các thay đổi của bạn nên kích hoạt phát hành:

• Patch: Sửa lỗi, cập nhật tài liệu
• Minor: Tính năng mới, thay đổi tương thích ngược
• Major: Thay đổi phá vỡ

🤝 Đóng góp

Chúng tôi hoan nghênh mọi đóng góp! Dưới đây là cách bắt đầu:

1. Fork kho lưu trữ và tạo nhánh tính năng
2. Thực hiện các thay đổi của bạn theo các quy ước mã ở trên
3. Kiểm thử các thay đổi của bạn bằng phiên bản Storybook nội bộ
4. Tạo changeset nếu các thay đổi của bạn xứng đáng được phát hành
5. Gửi pull request với mô tả rõ ràng

Trước khi gửi

• Mã xây dựng không có lỗi (pnpm build)
• Kiểm thử vượt qua (pnpm test:run)
• Mã được định dạng (pnpm format)
• Mã được lint (pnpm lint)
• Kiểm tra loại vượt qua (pnpm typecheck)
• Các thay đổi được kiểm thử với MCP inspector hoặc Storybook nội bộ
• Changeset được tạo nếu cần thiết (pnpm changeset)

Nhận trợ giúp

• Ý tưởng & Yêu cầu tính năng: Bắt đầu thảo luận
• Báo cáo lỗi: Mở vấn đề
• Câu hỏi: Hỏi trong GitHub Discussions

📄 Giấy phép

MIT - Xem LICENSE để biết chi tiết

---

Lưu ý: Dự án này đang thử nghiệm và đang được phát triển tích cực. API và kiến trúc có thể thay đổi khi chúng tôi khám phá những cách tốt nhất để tích hợp các tác nhân AI với Storybook.