Storybook MCP Server

Storybook MCP - Hướng dẫn cho Người đóng góp

Chào mừng đế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 UI và 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 người đóng góp muốn phát triển, kiểm thử hoặc đóng góp vào các gói này.

🚀 Bắt đầu Nhanh

Kiểm thử các 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

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

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ống hệt nhau ngoại trừ đường dẫn nguồn plugin tương đối, và việc xác thực gói 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 [email protected]

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, vì vậy 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 đến 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 với:

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 lập trình của mình đến nó tại http://localhost:6006/mcp (hoặc điểm cuối addon đã cấu hình của bạn) và dùng thử.

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 Bắt đầu.
5. Mở một cuộc trò chuyện trong VSCode và viết một lời nhắc như sau:

Cho tôi xem tất cả các câu chuyện về 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ó hoàn toàn sẵn sàng, 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 & Kiểm tra Mã

# 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

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

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

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

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

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 một changeset nếu các thay đổi của bạn nên kích hoạt một bản phát hành:

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

🤝 Đóng góp

Chúng tôi hoan nghênh các đóng góp! Đây là cách để bắt đầu:

1. Fork kho lưu trữ và tạo một nhánh tính năng
2. Thực hiện thay đổi của bạn tuân theo các quy ước mã ở trên
3. Kiểm thử thay đổi của bạn bằng cách sử dụng phiên bản Storybook nội bộ
4. Tạo một changeset nếu các thay đổi của bạn xứng đáng một bản phát hành
5. Gửi một 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)
• Các bài kiểm thử vượt qua (pnpm test:run)
• Mã được định dạng (pnpm format)
• Mã được kiểm tra (pnpm lint)
• Kiểm tra kiểu 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 một cuộc thảo luận
• Báo cáo Lỗi: Mở một 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 trong giai đoạn 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.