Storybook MCP Server

공식

에이전트가 UI 컴포넌트의 스토리를 자동으로 작성하고 테스트할 수 있도록 지원합니다.

GitHub
258

문서

Storybook MCP - 기여자 가이드

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

📦 패키지

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

  • @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 [email protected]

설치

# 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 인스펙터를 사용하여 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 앱 작업

프리뷰 스토리 도구의 일부로 렌더링되는 MCP 앱을 작업하고 디버깅하려면 다음을 수행할 수 있습니다:

  1. VSCode의 Insiders 빌드 사용
  2. chat.mcp.apps.enabled 설정이 활성화되어 있는지 확인
  3. 루트에서 pnpm storybook를 실행하여 저장소의 Storybook을 감시 모드로 시작
  4. VSCode를 다시 시작하고, .vscode/mcp.json 파일을 열어 Storybook MCP가 실행 중으로 표시되는지 확인하고, 그렇지 않으면 시작을 클릭합니다.
  5. VSCode에서 채팅을 열고 다음과 같은 프롬프트를 작성합니다:

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

  1. 이 첫 번째 프롬프트 이후, 변경할 때마다 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 pkg from '../package.json' with { type: 'json' };

🚢 릴리스 프로세스

이 프로젝트는 버전 관리를 위해 Changesets을 사용합니다:

# 1. Create a changeset describing your changes
pnpm changeset

PR을 생성할 때 변경 사항이 릴리스를 트리거해야 하는 경우 changeset을 추가합니다:

  • 패치: 버그 수정, 문서 업데이트
  • 마이너: 새로운 기능, 하위 호환 변경 사항
  • 메이저: 주요 변경 사항

🤝 기여하기

기여를 환영합니다! 시작하는 방법은 다음과 같습니다:

  1. 저장소를 포크하고 기능 브랜치를 생성합니다.
  2. 위의 코드 규칙에 따라 변경 사항을 적용합니다.
  3. 내부 Storybook 인스턴스를 사용하여 변경 사항을 테스트합니다.
  4. 변경 사항이 릴리스를 필요로 하는 경우 changeset을 생성합니다.
  5. 명확한 설명과 함께 풀 리퀘스트를 제출합니다.

제출 전 확인 사항

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

도움 받기

📄 라이선스

MIT - 자세한 내용은 LICENSE 참조

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