Cursor가 디자인 시스템 컴포넌트를 모르는 게 너무 답답해서 - MCP 도입기

AI는 똑똑하지만, Stack은 몰라요

최근 디자인 시스템 TF의 1차 목표가 마무리 되었는데요. 지금까지 약 20개가 넘는 컴포넌트, 토큰, 코어 등이 새롭게 개발되었으며, 이 중 대부분은 Compound 패턴으로 제공되는 복잡한 구조를 가지고 있어요.
이는 멀티 브랜드 디자인 시스템이다보니 각 프로덕트에서 다양한 디자인 요구 사항이 나올 수 있는데요, 이를 만족시키기 위한 방법으로 해당 패턴을 채택하여 디자인의 자유도를 높이고 있어요.

다만, 그로 인해 사용 초기 몇가지 문제가 발생하고 있었어요.

컴포넌트의 복잡성으로 인해 개발자가 컴포넌트를 사용하기 어려워요

• 어떤 prop이 있는지 모르고 있어서 코드를 작성하기 어려움
• 컴포넌트의 구조를 이해하기 어려움
• 여러 컴포넌트 간 조합하여 사용할 경우 코드 작성이 어려움 ex) Input과 Select 컴포넌트 조합

디자인 시스템 문서화는 스토리북을 통해 진행되고 있어요. 이를 통해 개발자가 컴포넌트를 사용하기 쉽게 도와주고 있어요. 사실 스토리북을 사용하여 위에서 제기한 문제 대부분을 해결할 수 있어요.

하지만 개발자 입장에선 스토리북을 매번 참고하기엔 너무 귀찮아요.

요즘 개발하실 때 Cursor, Claude, Claude Code 등의 도구들을 많이들 사용하실 거라 생각해요.

여기서 두번째 문제가 발생해요.

AI는 디자인 시스템을 모르고 있어요

• AI 도구들은 스토리북 문서를 제대로 읽지 못해요. (읽을 수는 있어도 유의미하고 정확한 정보를 얻기 어려워요)
• 정확한 정보를 주지 않으면 할루시네이션 현상이 발생해요.

예를 들어볼게요.

"React Hook Form과 Stack의 TextInput, Button 컴포넌트를 사용해서 로그인 폼을 만들어줘."

"Stack의 CustomModal을 사용해서 회원 탈퇴 팝업을 만들어줘."

막연하게 생각해보면 AI가 어떻게 이걸 이해할까?, 어떻게 이걸 만들어줄까? 라는 고민을 할 수밖에 없어요.

"그런 컴포넌트는 없는데요?"

다시 생각해볼까요? AI 도구들은 Stack이라는 디자인 시스템을 모르는데 어떻게 프롬프트를 이해할까요?

"Stack의 TextInput, Button 컴포넌트를 사용해서 로그인 폼을 만들어줘."

"Stack의 CustomModal을 사용해서 회원 탈퇴 팝업을 만들어줘."

Cursor는 어떻게 이걸 이해할까요?

Cursor는 워크스페이스 내 파일들을 참고해서 프롬프트를 어느정도 이해할 수 있어요.
다만, 워크스페이스 내에서 사용한 예시들만 맥락으로 갖고 있기에 구체적인 내용을 얻기 어려워요.

예를 들면 Select.Content 컴포넌트의 너비를 Select.Trigger 컴포넌트의 너비와 동일하게 만들어줘 라는 프롬프트를 작성했을 때 참고할만한 코드가 워크스페이스 내에 존재하지 않는다면 해당 코드를 생성할 수 없어요.

Claude Code는 어떻게 이걸 이해할까요?

Cursor와 동일하다고 생각하시면 될 것 같아요.

Claude는 어떻게 이걸 이해할까요?

Claude는 해당 프롬프트만으로는 정확하게 이해할 수 없어요. 따라서 "그런 컴포넌트는 없는데요?" 라는 답변을 하게 되죠.

Q: "Stack의 TextInput, Button 컴포넌트를 사용해서 로그인 폼을 만들어줘."
A: "Stack 디자인 시스템의 정확한 CustomModal 구조를 찾을 수 없어서, 일반적인 Modal 구조를 기반으로 회원 탈퇴 팝업을 만들어드리겠습니다."

물론 열심히 잘 만들어주긴 해요. 다만 제가 원하는 건 Stack 디자인 시스템의 정해진 규칙을 잘 준수하는 컴포넌트를 사용하는 것이에요.

그럼 어떻게 해야할까요?

정말 간단하게도 디자인 시스템의 구체적인 명세를 제공하면 해결할 수 있어요.

여러 방법이 있겠지만 우선 LLMs.txt를 설명드릴게요.

LLMs.txt

Stack 디자인 시스템을 만들 때 여러 라이브러리를 참고했는데요, 그 중 하나가 Chakra-UI 라이브러리예요.

Chakra-UI에서는 LLMs.txt를 제공하는데요, 이 텍스트 파일은 Cursor, Claude, Claude Code 등의 도구들이 Chakra-UI를 이해할 수 있도록 도와주는 파일이에요.

컴포넌트의 구체적인 사용 코드 예시를 제공하고 있어서 AI가 컴포넌트를 이해하고 사용할 수 있어요.
아래는 일부 내용을 가져왔어요.

// ### Form LLM
 
// Here's an example of a popover with a form inside.
 
import {
  Button,
  Field,
  Input,
  Popover,
  Portal,
  Stack,
  Textarea,
} from "@chakra-ui/react"
 
export const PopoverWithForm = () => {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <Button size="sm" variant="outline">
          Click me
        </Button>
      </Popover.Trigger>
      <Portal>
        <Popover.Positioner>
          <Popover.Content>
            <Popover.Arrow />
            <Popover.Body>
              <Stack gap="4">
                <Field.Root>
                  <Field.Label>Width</Field.Label>
                  <Input placeholder="40px" />
                </Field.Root>
                <Field.Root>
                  <Field.Label>Height</Field.Label>
                  <Input placeholder="32px" />
                </Field.Root>
                <Field.Root>
                  <Field.Label>Comments</Field.Label>
                  <Textarea placeholder="Start typing..." />
                </Field.Root>
              </Stack>
            </Popover.Body>
            <Popover.CloseTrigger />
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.Root>
  )
}

이렇게 했을 때 이런 점이 좋아요

• Cursor나 Claude와 같은 AI 도구에서 해당 파일을 Context로 포함하여 제공하면 AI는 해당 파일을 참고하여 코드를 생성할 수 있어요.

아쉬운 점도 존재해요

• LLMs.txt는 모든 컴포넌트의 정보를 포함하고 있어요. 따라서 토큰 소비량이 많을 수 있어요.
  (chakra의 llms-full.txt 파일 토큰 카운팅 했을 때 397,180 토큰을 사용해요)
  이로 인해 작은 컨텍스트 단위로 나눈 파일도 제공하는 것이 좋아요.

단순 텍스트 제공 vs. MCP

처음엔 저도 간단하게 생각했어요. "그냥 Stack 컴포넌트들 정보를 쭉 정리해서 하나의 거대한 텍스트 파일로 만들면 되지 않을까?"

Chakra-UI처럼 LLMs.txt 방식으로 해결하면 될 것 같았거든요. 하지만 실제로 고민해보니 이 방식도 몇 가지 아쉬운 점들이 있었어요.

우선 토큰을 너무 많이 사용해요
Chakra-UI의 경우 전체 명세가 397,180 토큰인데, Stack도 비슷할 거라 생각하니,, 매번 이 정도 토큰을 컨텍스트에 포함시키면 비용도 많이 들고, 일부 도구에서는 컨텍스트 윈도우를 초과할 수도 있어요.

업데이트가 번거로워요
Stack 컴포넌트가 업데이트될 때마다 개개인이 텍스트 파일을 수동으로 업데이트해야 하는데, 이게 은근히 신경 쓸 일이 많아져요. 실수로 빼먹으면 AI가 구버전 정보를 참고하게 되고요.

거대한 텍스트에서 정보 찾기도 까다로워요
AI가 몇십만 토큰 되는 텍스트에서 원하는 정보를 정확히 파싱하는 건 생각보다 오류가 발생하기 쉬워요. "TextInput 컴포넌트의 props 정보만 달라"고 해도 다른 컴포넌트 정보까지 섞여서 나올 수 있거든요.

확장성도 좋지 않아요
새로운 컴포넌트가 추가될 때마다 텍스트 파일이 계속 커지고, 관리하기도 점점 어려워져요. 그리고 generate-component-code 같은 "액션"은 단순 텍스트로는 구현할 수 없고요.

이런 문제들 때문에 MCP라는 다른 접근 방식을 선택하게 되었어요.

MCP를 사용하면 이런 점들이 좋아져요

1. 필요한 정보만 딱 가져와요
   "TextInput 정보만 달라"고 하면 TextInput 정보만 정확히 제공하니까 토큰도 훨씬 적게 들고, 정보도 더 정확해요.

2. 항상 최신 정보를 보장해요
   @latest로 설정해두면 패키지가 업데이트될 때마다 자동으로 최신 버전을 사용하게 되어서 별도 관리가 필요 없어요.

3. 구조화된 질문이 가능해요
   "이 컴포넌트의 props가 뭐야?", "사용 예시 보여줘", "코드 생성해줘" 같은 구체적인 질문을 통해 원하는 정보를 정확히 얻을 수 있어요.

4. 확장하기 쉬워요
   새로운 기능이 필요하면 도구만 추가하면 되고, 기존 도구를 수정하는 것도 간단해요.

5. 단순 정보 제공을 넘어서요
   정보를 알려주는 것뿐만 아니라 실제 코드를 생성하거나, 컴포넌트를 추천하는 등의 "액션"까지 수행할 수 있어요.

MCP (Model Context Protocol)

그렇다면 MCP에 대해 간략하게 알아볼까요?

MCP는 Model Context Protocol의 줄임말로, AI 애플리케이션이 데이터 소스나 도구에 접근할 수 있도록 도와주는 표준화된 프로토콜이에요.

MCP는 어떻게 동작하나요?

MCP는 클라이언트-서버 구조로 동작해요.

• MCP 클라이언트: Claude Desktop, Cursor 같은 AI 도구들
• MCP 서버: 특정 기능을 제공하는 가벼운 프로그램들 (Stack MCP가 여기에 해당)
• 데이터 소스: 파일, 데이터베이스, API 등 실제 정보가 저장된 곳

예를 들어 Claude Desktop or Cursor(클라이언트)가 Stack MCP 서버에게 "TextInput 컴포넌트 정보 달라"고 요청하면, Stack MCP 서버가 해당 정보를 찾아서 클라이언트에게 전달해주는 방식이에요.

또 다른 예시로 GitHub MCP Server를 생각해볼까요?

GitHub MCP Server가 없었다면 Claude나 Cursor에서는 "이 레포지토리의 최근 커밋 내역 알려줘"나 "이 PR에서 어떤 변경사항이 있었는지 정리해줘" 같은 요청을 할 수 없었을 거에요. AI가 GitHub 정보에 직접 접근할 방법이 없었으니까요.

하지만 GitHub MCP Server를 사용하면 이런 요청을 할 수 있어요.

• Repository의 코드와 파일 구조 탐색
• Pull Request 정보와 코드 리뷰 내용 확인
• Issue 트래킹과 커밋 히스토리 조회
• Branch 정보와 변경사항 분석

Stack MCP도 마찬가지예요. AI가 우리 디자인 시스템 정보에 직접 접근할 수 있게 해주는 "전용 다리" 역할을 하는 거죠.

왜 MCP를 선택했을까요?

처음부터 무조건 MCP를 써야겠어! 라는 이유로 선택하진 않았어요.

앞서 작성한 문제들을 해결하기 위해 다른 방법들을 찾아보다가 우연히 발견했어요. 그러다 MCP 설명에서 "응용 프로그램이 LLM에 컨텍스트를 제공하는 방법을 표준화하는 공개 프로토콜입니다" 라는 문구를 보고 지금 상황에 적합하지 않을까? 라는 생각을 했어요.

1. AI 도구들과의 호환성
   Claude Desktop은 물론이고, 앞으로 MCP를 지원하는 다른 AI 도구들도 계속 늘어나고 있어요. 한 번 만들어두면 여러 도구에서 사용할 수 있다는 게 매력적이었어요. 지금도 벌써 Cursor에서 MCP를 지원하고 있어요.

2. 표준화된 방식
   각 AI 도구마다 다른 방식으로 컨텍스트를 제공해야 한다면 관리하기 어려웠을 텐데, MCP는 표준화된 방식이라 한 번 구현하면 끝이에요.

3. 확장 가능성
   지금은 Stack 컴포넌트 정보만 제공하지만, 나중에는 디자인 토큰 정보나 다른 회사 도구들과도 연동할 수 있어요. MCP의 표준화된 구조 덕분에 확장하기 쉬워요.

4. 실시간 업데이트
   가장 중요한 부분인데, 패키지로 배포하면 항상 최신 정보를 제공할 수 있어요. 개발자들이 따로 업데이트할 필요도 없고요. (캐시를 날려야 할 때도 있지만요 😅)

5. 구조화된 상호작용
   단순히 텍스트를 제공하는 게 아니라, "이 컴포넌트의 props가 뭐야?", "코드 생성해줘" 같은 구체적인 질문에 정확한 답변을 할 수 있어요.

요런 이유들로 최종적으로 MCP를 선택했어요.

Stack MCP

그래서 Stack MCP는 어떻게 만들어졌을까요?

Stack MCP를 만들면서 가장 고민했던 부분은 "어떻게 하면 AI가 Stack 컴포넌트를 정확하게 이해하고 사용할 수 있게 할까?"였어요.

단순히 스토리북 링크만 던져주는 건 의미가 없었거든요. AI가 실제로 활용할 수 있는 형태로 정보를 구조화해야 했어요.

AI/LLM Specification Template 개발

첫 번째로 한 일은 AI가 이해하기 쉬운 문서 형식을 만드는 것이었어요.

기존의 개발자용 문서는 사람이 읽기엔 좋지만, AI가 파싱하기엔 애매한 부분들이 많았어요. 그래서 다음과 같은 구조화된 템플릿을 개발했어요

# TextInput - AI/LLM Specification Template
 
## Component Metadata
- 컴포넌트 기본 정보 (이름, 카테고리, 버전 등)
- Compound 패턴 여부와 서브 컴포넌트 목록
- 접근성 지원 정보
 
```json
{
  "name": "TextInput",
  "compound": false,
  "subComponents": [],
  "accessibility": {
    "ariaSupport": true,
    "keyboardNavigation": true
  }
}
 
## Import Statement
- 정확한 import 방법과 사용 예시
 
## Component Interface
- TypeScript 인터페이스 정의
- Props별 상세 설명과 예시
 
## Usage Examples
- 기본 사용법부터 고급 사용법까지
- 실제 프로젝트에서 쓸 만한 완전한 예시
 
## Best Practices & Anti-patterns
- ✅ 올바른 사용법
- ❌ 피해야 할 사용법

특히 Compound 패턴을 많이 사용하다 보니 각 서브 컴포넌트들의 관계와 올바른 조합 방법을 명확히 설명하는 게 중요했어요.

6가지 도구 제공

Stack MCP는 개발자들이 실제로 필요로 하는 6가지 핵심 기능을 도구로 제공해요.

1. list-components: "뭐가 있더라?"
   

{
  "components": [
    {
      "name": "TextInput",
      "category": "Form",
      "description": "단일 행 텍스트 입력 컴포넌트",
      "compound": false,
      "keywords": ["input", "form", "text"]
    },
    {
      "name": "BottomSheet", 
      "category": "Overlay",
      "description": "하단에서 올라오는 모달 컴포넌트",
      "compound": true,
      "subComponents": ["Root", "Trigger", "Content", "Header"]
    }
  ]
}

• 카테고리별 그룹화: Form, Layout, Overlay 등으로 분류해서 볼 수 있어요
• Compound 패턴 정보: 복합 컴포넌트인지, 어떤 서브 컴포넌트들이 있는지 한눈에 파악
• 키워드 미리보기: 각 컴포넌트가 어떤 용도인지 키워드로 빠르게 이해

2. get-component-info: "이거 어떻게 써?"
   

특정 컴포넌트의 모든 정보를 종합적으로 제공해요. 프롬프트를 입력하면 가장 많이 사용되는 도구예요.

• 메타데이터: 패키지 정보, 버전, 카테고리, 설명
• Import 방법: 정확한 import 구문과 사용 예시
• Props 테이블: 모든 props의 타입, 필수 여부, 기본값, 설명
• 사용 예시: 기본 사용법부터 고급 사용법까지 완전한 코드
• 접근성 정보: ARIA 지원, 키보드 네비게이션 등
• 베스트 프랙티스: 올바른 사용법과 피해야 할 패턴

특히 Base 컴포넌트 참조를 올바르게 하도록 만들어 주는 게 중요했어요.

이렇게 하면 AI가 "BottomSheet.Title에 font prop을 줄 수 있나?"라는 질문을 받았을 때, Text 컴포넌트의 정보까지 참고해서 정확한 답변을 할 수 있어요.

3. search-components: "버튼 같은 거 없나?"
   

키워드로 컴포넌트를 찾아주는 도구예요.

{
  "results": [
    {
      "componentName": "Button",
      "relevanceScore": 10,
      "matchedFields": ["name"],
      "snippet": "기본 버튼 컴포넌트로 클릭 이벤트를 처리합니다"
    },
    {
      "componentName": "IconButton", 
      "relevanceScore": 8,
      "matchedFields": ["name", "keywords"],
      "snippet": "아이콘만 있는 버튼 컴포넌트"
    }
  ]
}

검색 알고리즘은 아래와 같아요.

• 컴포넌트 이름이 완벽하게 매칭: 10점
• 키워드 매칭: 5점
• 설명 내용 매칭: 3점
• 카테고리 매칭: 2점
• 서브 컴포넌트 매칭: 1점

"input"을 검색하면 TextInput이 가장 위에 나오고, MultiSelect, RadioGroup 같은 관련 컴포넌트들도 적절한 순서로 나와요.

이 부분이 완벽하게 정확할 필요는 없어요. 중요한 건 AI가 능동적으로 관련 컴포넌트를 찾을 수만 있으면 돼요.

관련성 점수를 바탕으로 반환한 데이터를 활용해 AI가 자체적으로 판단하게 하는 게 중요했어요.

4. generate-component-code: "바로 쓸 수 있는 코드 만들어줘"
   

이 부분은 간단한 코드 예시들을 제공해요.

5. get-component-props: "이 prop이 정확히 뭐하는 거야?"
   

Props 정보를 상세하게 조회하는 도구예요. 복합 컴포넌트의 서브 컴포넌트별 props도 지원해요.

컴포넌트의 모든 props 정보를 완전한 형태로 제공해줘요. 각 prop의 타입, 필수 여부, 기본값, 상세 설명까지 포함해서 AI가 정확하게 판단할 수 있도록 도와줘요.

AI가 "TextInput에 rightAddon prop으로 뭘 넣을 수 있어?"라는 질문을 받으면, 이 도구로 rightAddon: ReactNode 정보를 확인하고 "아이콘이나 버튼 같은 React 요소를 넣을 수 있어요"라고 정확하게 답변할 수 있어요.

도구들의 협력 메커니즘

이 6가지 도구는 독립적으로 작동하지만, AI가 복잡한 요청을 처리할 때는 여러 도구를 조합해서 사용해요.

"로그인 폼을 만들어줘"라는 요청이 들어오면 다음과 같은 흐름으로 동작해요.

1. search-components → "form", "input", "button" 관련 컴포넌트 찾기
2. get-component-info → TextInput, Button 상세 정보 조회
3. generate-component-code → 각 컴포넌트의 기본 코드 생성
4. AI가 종합해서 완전한 로그인 폼 코드 작성

도입 효과

Stack MCP는 2025년 6월 5일에 처음 배포되었어요.

Figma MCP와의 시너지 효과

Figma MCP와 함께 사용하니 UI 구현이 훨씬 수월해졌어요.

기존 워크플로우

1. 디자이너가 Figma에서 디자인 작업
2. 개발자가 Figma 열어서 디자인 확인
3. 스토리북 문서 찾아서 컴포넌트 사용법 확인
4. 코드 작성하면서 props 맞춰가며 구현

MCP 도입 후 워크플로우

1. 디자이너가 Figma에서 디자인 작업
2. 개발자가 AI에게 "이 Figma 디자인대로 구현해줘" + Figma 링크 제공
3. AI가 Figma MCP로 디자인 분석 → Stack MCP로 컴포넌트 정보 조회 → 바로 코드 생성

아래는 Checkbox 컴포넌트를 커스텀한 형태인데요, Figma Node 링크만 제공하면 쉽게 구현할 수 있었어요.

실제 동작 메커니즘

1. Figma MCP 호출 → 디자인 요소 분석 (체크박스, 라벨, 스타일 등)
2. list-components 호출 → "checkbox" 관련 컴포넌트 검색
3. get-component-info 호출 → Checkbox 컴포넌트 상세 정보 조회
4. AI 종합 판단 → Figma 디자인 + Stack 컴포넌트 정보 결합하여 코드 생성

되게 재밌는 점은 AI가 디자인을 보고 "이 디자인은 어떤 상황에서 사용되는 건가?"까지 추론하고 있다는 거예요. 단순히 코드만 생성하는 것이 아니라 디자인의 의도까지 파악해서 적절한 컴포넌트 조합을 제안해주고 있어요.

개발 생산성 향상

컴포넌트 정보 검색 시간 단축

• 기존: 스토리북 → 컴포넌트 페이지 → props 테이블 확인 (평균 2-3분)
• MCP 도입 후: AI에게 질문 → 즉시 답변 (평균 10-20초)

코드 작성 시간 단축

• 기존: 예시 코드 찾기 → 복사 → 수정 → props 맞추기
• MCP 도입 후: 요구사항 설명 → 완성된 코드 생성

학습 곡선 완화

새로운 팀원이 Stack을 사용할 때 "이 컴포넌트 어떻게 써요?" 같은 질문을 팀원들에게 하는 대신, AI에게 물어보고 바로 해결할 수 있게 되었어요.

전파

디자인 시스템은 만들었다고 끝나는 것이 아닌 것 같아요. 전파가 가장 중요하다고 생각해요.

MCP도 나름 디자인 시스템 전파에 긍정적인 영향을 끼치고 있다고 생각해요.

마치며

아직은 완벽하지 않은 점들도 있어요. 특히 조합하여 사용하는 부분, Select.Trigger는 FieldBox와 같은 컴포넌트들과 조합하여 사용할 수 있는데 이 부분은 아직 개선이 필요해요.

더불어 문서도 다시 한번 점검해야 할 것 같아요. 이 글을 작성하며 문서에서 잘못된 부분을 발견했어요 😅

References

• hallucinations
• context-windows
• token-counting
• cursor-models
• Model Context Protocol