Storybook MCP 서버

Node CI npm license

Storybook 문서 및 컴포넌트 정보와 상호작용하기 위한 도구를 제공하는 Model Context Protocol (MCP) 서버입니다.

기능

getComponentList: 구성된 Storybook에서 모든 컴포넌트 목록을 가져옵니다.
getComponentsProps: 헤드리스 브라우저 자동화를 사용하여 여러 컴포넌트에 대한 상세 속성(props) 정보를 가져옵니다.
Custom Tools: JavaScript를 사용하여 Storybook 페이지에서 원하는 정보를 추출할 수 있는 사용자 정의 도구를 생성합니다.

Related MCP server: MCP Server

설치 및 구성

MCP 설정

MCP 설정에 다음 구성을 추가하세요:

{
  "mcpServers": {
    "storybook": {
      "command": "npx",
      "args": ["-y", "storybook-mcp@latest"],
      "env": {
        "STORYBOOK_URL": "<your_storybook_url>/index.json"
      }
    }
  }
}

storybook-mcp는 즉시 시작되며 처음 실행될 때 백그라운드에서 Chromium을 설치합니다. 브라우저를 미리 설치하려면 npx -y storybook-mcp@latest install-browser를 실행하세요. 다운로드가 완료되기 전까지는 첫 번째 브라우저 기반 도구 호출에 시간이 더 걸릴 수 있습니다.

환경 변수

STORYBOOK_URL (필수): Storybook의 index.json 파일에 대한 URL
CUSTOM_TOOLS (선택 사항): Storybook에서 특정 정보를 추출하기 위한 사용자 정의 도구 정의를 담은 JSON 배열

사용법

이 서버는 내장 도구를 제공하며 사용자 정의 도구를 지원합니다:

내장 도구

1. getComponentList

구성된 Storybook에서 사용 가능한 모든 컴포넌트 목록을 검색합니다.

예시:

Available components:
Accordion
Avatar
Badge
Button
...

2. getComponentsProps

다음 정보를 포함하여 여러 컴포넌트에 대한 상세 속성(props) 정보를 가져옵니다:

속성 이름
타입
기본값
설명
필수/선택 여부

매개변수:

componentNames (문자열 배열): 속성 정보를 가져올 컴포넌트 이름 배열

사용 예시:

Tool: getComponentsProps
Parameters: { "componentNames": ["Button", "Input", "Avatar"] }

사용자 정의 도구

Storybook 페이지에서 특정 정보를 추출하기 위한 사용자 정의 도구를 정의할 수 있습니다. 각 사용자 정의 도구는 다음을 수행할 수 있습니다:

Storybook의 모든 페이지로 이동
사용자 정의 JavaScript를 실행하여 데이터 추출
AI 어시스턴트에게 구조화된 데이터 반환

사용자 정의 도구 구조:

interface CustomTool {
  name: string; // Unique tool name
  description: string; // Tool description for the AI
  parameters: object; // Input parameters schema (optional)
  page: string; // URL to navigate to
  handler: string; // JavaScript code to execute on the page
}

사용자 정의 도구 예시:

[
  {
    "name": "getIconList",
    "description": "Get All Icons from the Icon page",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/icon--docs",
    "handler": "Array.from(document.querySelectorAll('.icon-name')).map(i => i.textContent)"
  },
  {
    "name": "getColorPalette",
    "description": "Extract color palette from design tokens",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/design-tokens--colors",
    "handler": "Array.from(document.querySelectorAll('.color-swatch')).map(el => ({ name: el.getAttribute('data-color-name'), value: el.style.backgroundColor }))"
  }
]

더 많은 예시와 자세한 문서는 examples/custom-tools-example.md를 참조하세요.

예시

STORYBOOK_URL 및 CUSTOM_TOOLS 환경 변수로 Spectrum storybook-mcp 구성을 설정합니다.

{
  "mcpServers": {
    "storybook-mcp": {
      "command": "npx",
      "args": ["-y", "storybook-mcp@latest"],
      "env": {
        "STORYBOOK_URL": "https://opensource.adobe.com/spectrum-web-components/storybook/index.json",
        "CUSTOM_TOOLS": "[{\"name\":\"getIconList\",\"description\":\"Get All Icons from the Icon page\",\"parameters\":{},\"page\":\"https://opensource.adobe.com/spectrum-web-components/storybook/iframe.html?viewMode=docs&id=icons--docs&globals=\",\"handler\":\"Array.from(document.querySelector('icons-demo').shadowRoot.querySelectorAll('.icon')).map(i => i.textContent)\"}]"
      }
    }
  }
}

작동 원리

컴포넌트 목록: 서버가 Storybook의 index.json 파일(v3는 stories.json)을 가져와 "docs" 타입으로 표시된 모든 컴포넌트를 추출합니다.
속성 정보: 컴포넌트 속성의 경우, 서버는 다음을 수행합니다:
- index.json에서 컴포넌트의 문서 ID를 찾습니다.
- 컴포넌트 문서 페이지를 위한 iframe URL을 구성합니다.
- Playwright를 사용하여 헤드리스 브라우저에서 페이지를 로드합니다.
- 문서에서 속성 테이블 HTML을 추출합니다.

지원되는 Storybook URL

이 서버는 index.json 파일(v3는 stories.json)을 노출하는 모든 Storybook에서 작동합니다. 일반적인 패턴은 다음과 같습니다:

https://your-storybook-domain.com/index.json
https://your-storybook-domain.com/storybook/index.json

개발

로컬 개발

저장소를 복제합니다.
의존성을 설치합니다: yarn install
Playwright 브라우저를 설치합니다: yarn install:browser
환경 변수를 설정합니다: export STORYBOOK_URL="your-storybook-url"
개발 모드에서 실행합니다: yarn dev

참고: 원한다면 yarn dev 대신 npx @modelcontextprotocol/inspector tsx src/index.ts를 사용할 수도 있습니다.

빌드

yarn build

테스트

yarn test

요구 사항

Node.js 18.0.0 이상
Playwright가 설치한 Chromium 브라우저

오류 처리

서버는 다음 상황에 대한 포괄적인 오류 처리를 포함합니다:

누락되었거나 잘못된 Storybook URL
네트워크 연결 문제
컴포넌트를 찾을 수 없는 경우
Playwright 브라우저 자동화 실패

라이선스

Storybook MCP는 MIT 라이선스를 따릅니다.

storybook-mcp