Storybook MCP

[!TIP] 이 저장소는 Storybook v10.6.0부터 storybookjs/storybook로 이동했습니다. 업데이트된 문서는 해당 저장소를 확인하세요.

---

Storybook MCP

Storybook MCP Addon 모노레포에 오신 것을 환영합니다! 이 프로젝트는 AI 에이전트가 Storybook과 더 효율적으로 작업할 수 있도록, UI 컴포넌트 정보와 개발 워크플로우를 제공하는 MCP(Model Context Protocol) 서버를 노출합니다.

📦 패키지

이 모노레포는 네 개의 주요 패키지를 포함합니다:

• @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

저장소는 의도적으로 마켓플레이스 카탈로그를 두 곳에 유지합니다. 루트 카탈로그는 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 인스턴스
• 변경 사항이 자동으로 반영되도록 watch 모드의 애드온
• http://localhost:6006/mcp에서 사용 가능한 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

테스트

모노레포는 각 패키지에 대해 구성된 프로젝트와 함께 루트 수준의 중앙 집중식 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을 watch 모드로 시작하세요
4. VSCode를 다시 시작하고 .vscode/mcp.json 파일을 열어 Storybook MCP가 실행 중으로 표시되는지 확인하고, 그렇지 않으면 시작을 클릭하세요
5. VSCode에서 채팅을 열고 다음과 같은 프롬프트를 작성하세요:

Storybook MCP를 사용하여 모든 버튼 스토리가 어떻게 보이는지 보여줘

6. 이 첫 번째 프롬프트 후, 변경할 때마다 Storybook이 자동으로 다시 시작됩니다. 완전히 준비될 때까지 기다린 후 "도구를 다시 실행" 프롬프트를 사용하세요.

MCPJam의 inspector를 사용하여 도구 호출을 더 낮은 수준으로 제어할 수도 있습니다.

포맷팅 및 린팅

# 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 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. 저장소를 포크하고 기능 브랜치를 만드세요
2. 위의 코드 규칙에 따라 변경하세요
3. 내부 Storybook 인스턴스를 사용하여 변경 사항을 테스트하세요
4. 변경 사항이 릴리스를 필요로 하는 경우 changeset을 만드세요
5. 명확한 설명과 함께 풀 리퀘스트를 제출하세요

제출 전

• 코드가 오류 없이 빌드됨 (pnpm build)
• 테스트 통과 (pnpm test:run)
• 코드가 포맷됨 (pnpm format)
• 코드가 린트됨 (pnpm lint)
• 타입 검사 통과 (pnpm typecheck)
• MCP inspector 또는 내부 Storybook으로 변경 사항 테스트됨
• 필요한 경우 changeset 생성됨 (pnpm changeset)

도움 받기

• 아이디어 및 기능 요청: 토론 시작
• 버그 신고: 이슈 열기
• 질문: GitHub Discussions에서 문의하세요

📄 라이선스

MIT - 자세한 내용은 LICENSE를 참조하세요

---

참고: 이 프로젝트는 실험적이며 활발히 개발 중입니다. AI 에이전트를 Storybook과 통합하는 최선의 방법을 탐색하면서 API와 아키텍처가 변경될 수 있습니다.