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 추가하기

또한 패키지에 MCP 서버를 stdio 모드로 시작하기 위한 CLI 진입점을 추가했습니다.

// 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 컴포넌트를 사용해 필터링 가능한 콘텐츠 목록을 구현해 줘