Mintel에서는 자체 React 디자인 시스템 컴포넌트 라이브러리를 운영하고 있습니다. 프로덕트 디자인 팀과 협업해 디자인 시스템 기준을 컴포넌트 구현에 녹여내고, Storybook을 이용해 문서화하고 있습니다.

개발 워크플로에서 AI 에이전트 활용이 늘어나면서, 디자인 시스템 npm 패키지에 로컬 MCP CLI를 함께 제공해 디자인 시스템 문서를 노출할 수 있는 방법을 모색하고자 했습니다.

@storybook/addon-mcp

Storybook 팀은 MCP(Model Context Protocol) 서버를 통해 Storybook 문서를 노출하는 @storybook/addon-mcp를 초기 개발 단계에서 진행하고 있습니다. 이를 통해 AI 에이전트가 컴포넌트 라이브러리 문서를 구조화된 방식으로 조회할 수 있으며, Storybook 스토리 생성을 돕는 도구도 제공됩니다.

Storybook 10으로 업그레이드한 뒤 .storybook/main.ts에 애드온 설정을 추가했습니다:

const config: StorybookConfig = {
  addons: ["@storybook/addon-mcp"],
  features: {
    experimentalComponentsManifest: true,
  },
};

컴포넌트 매니페스트를 생성하려면 Storybook 10과 React가 모두 필요합니다. 이를 통해 props와 API 문서를 비롯한 각 컴포넌트에 대한 더 자세한 정보를 노출할 수 있습니다.

이 애드온은 Storybook을 로컬에서 실행할 때 MCP 서버를 함께 시작하며, http://localhost:6006/mcp에서 서버에 접속할 수 있습니다.

{
  "mcpServers": {
    "storybook-mcp": {
      "url": "http://localhost:6006/mcp",
      "type": "http"
    }
  }
}

MCP 서버는 Storybook을 빌드할 때 manifests 디렉터리에 파일을 생성하는 방식으로 동작합니다. 이 파일들에는 컴포넌트 메타데이터와 문서가 구조화된 형식으로 담겨 있습니다.

다른 팀에 MCP 제공하기

이 애드온은 디자인 시스템 자체를 개발하는 개발자에게 유용하지만, 디자인 시스템을 사용하는 다른 개발 팀도 MCP 서버를 활용할 수 있게 하고자 했습니다.

이를 위해 내부의 @storybook/mcp 패키지를 활용해 라이브러리에 CLI를 추가하여 MCP 서버를 stdio 모드로 실행할 수 있도록 했습니다. 그러면 다른 팀에서도 pnpm dlx <library-name>@latest 명령어 하나로 디자인 시스템 라이브러리 MCP 서버의 최신 버전을 실행할 수 있습니다.

빌드 프로세스

라이브러리 빌드 프로세스를 확장해 Storybook도 함께 빌드하고, 생성된 매니페스트를 배포되는 패키지에 복사하도록 했습니다.

# Build the storybook
pnpm build-storybook
# Copy manifest files into package dist
mkdir -p ./dist/manifests
cp -r ./storybook-static/manifests/ ./dist/manifests/
# Build the library
pnpm vite build

CLI 추가하기

또한 패키지에 CLI 진입점을 추가해 MCP 서버를 stdio 모드로 시작할 수 있도록 했습니다.

// package.json
{
  "bin": "./dist/mcp.js"
}

#!/usr/bin/env node

import { McpServer } from "tmcp";
import { ValibotJsonSchemaAdapter } from "@tmcp/adapter-valibot";
import { StdioTransport } from "@tmcp/transport-stdio";
import {
  type StorybookContext,
  addListAllDocumentationTool,
  addGetDocumentationTool,
} from "@storybook/mcp";
import fs from "node:fs/promises";
import pkgJson from "./package.json";

const adapter = new ValibotJsonSchemaAdapter();
const server = new McpServer(
  {
    name: pkgJson.name,
    version: pkgJson.version,
    description: pkgJson.description,
  },
  {
    adapter,
    capabilities: {
      tools: { listChanged: true },
    },
    instructions:
      "You can use this MCP server to access Mintel Design System documentation, with component API docs for the React component library.",
  }
).withContext<StorybookContext>();

addListAllDocumentationTool(server).then(() => {
  addGetDocumentationTool(server).then(() => {
    const transport = new StdioTransport(server);

    transport.listen({
      format: "markdown",
      manifestProvider: async (_request, path) =>
        fs.readFile(`${__dirname}/${path}`, "utf-8"),
    });
  });
});

사용법

이제 팀에서는 Cursor와 같은 IDE를 설정해 MCP 서버를 로컬에서 실행하도록 구성할 수 있습니다:

{
  "mcpServers": {
    "mintel-design-system": {
      "command": "pnpm",
      "args": ["dlx", "<package-name>@latest"]
    }
  }
}

프로젝트에서 사용하는 디자인 시스템 라이브러리의 특정 버전을 이용해 프로젝트 단위로 실행되도록 설정할 수도 있습니다:

{
  "mcpServers": {
    "mintel-design-system": {
      "command": "pnpm",
      "args": ["exec", "<package-name>"]
    }
  }
}

MCP 서버를 가장 효과적으로 활용하는 방법을 아직 모색 중이지만, 다음과 같은 프롬프트에서 이미 유용하게 쓰이고 있습니다:

이 코드베이스에서 Mintel Design System 컴포넌트로 교체할 수 있는 컴포넌트가 있는지 평가해 줘

새로운 Mintel Design System Button 컴포넌트로 마이그레이션하기 위한 계획을 세워 줘

Mintel Design System 컴포넌트를 사용해 필터링 가능한 콘텐츠 목록을 구현해 줘