요약 (TL;DR)
컴포넌트 라이브러리 MCP 서버는 코딩 에이전트에게 카탈로그 검색, 실제 props 및 디자인 규칙 읽기, 설치된 버전 확인 등의 도구를 제공하여, 에이전트가 학습 데이터에서 API를 추측하는 것을 방지합니다. 이는 세 가지 보조 요소와 가장 잘 작동합니다: 에이전트에게 언제 해당 도구를 호출해야 하는지 알려주는 짧은 규칙 파일, MCP가 없는 에이전트를 위한 llms.txt 및 Markdown 문서, 그리고 실제 파일을 작성하고 버전을 기록하는 레지스트리(registry)와 CLI입니다.
Claude Code에 설정 페이지를 요청하면 1분 만에 작성해 줄 것입니다. 또한 라이브러리에 존재하지 않았던 <Button intent="primary"> 같은 것을 만들거나, 토큰이 속해야 할 곳에 #3b82f6을 하드코딩하거나, 이미 가지고 있는 날짜 선택기를 다시 구축할 수도 있습니다. 컴포넌트 라이브러리 MCP 서버는 이 문제를 근본적으로 해결합니다: 에이전트가 무엇이 존재하는지 조회하고, 실제 props를 읽고, 실제 파일을 설치할 수 있는 도구를 제공하는 것입니다. 본 가이드는 React 컴포넌트 라이브러리가 Claude Code, Cursor, Codex에 자신을 노출시키는 방법, 작동하게 만드는 네 가지 요소(MCP 서버, 규칙 파일, llms.txt, 레지스트리), 그리고 CLI가 작성해 주는 설정을 다룹니다.
우리는 Wingo UI를 구축하므로 예제는 우리의 서버, CLI 및 레지스트리를 사용하며, 출력은 릴리스 1.7.0에서 복사되었습니다. 이 접근 방식은 내부 디자인 시스템을 포함하여 모든 라이브러리에 적용되며, 다른 도구가 더 적합한 경우 그렇게 명시합니다. 에이전트 및 UI에 대한 더 짧은 가이드는 AI 에이전트를 사용한 UI 구축 아래에서 확인할 수 있습니다: 규칙 파일의 경우 AGENTS.md vs CLAUDE.md vs Cursor rules, shadcn MCP 서버와 두 번째 레지스트리를 위한 Claude Code shadcn 설정, 그리고 구축하는 화면 자체가 채팅인 경우를 위한 React AI 채팅 UI 가이드가 있습니다.
컴포넌트 라이브러리 MCP 서버란 무엇인가요?
컴포넌트 라이브러리 MCP 서버는 UI 라이브러리를 에이전트가 호출할 수 있는 도구로 변환하는 Model Context Protocol 서버입니다. 이 서버를 통해 카탈로그 검색, 특정 컴포넌트의 props 및 사용법 읽기, 디자인 규칙 가져오기, 그리고 설치된 버전과 최신 릴리스 비교가 가능합니다. 에이전트는 기억하는 대신 질문하게 됩니다.
클라이언트(Claude Code, Cursor, Codex, Gemini CLI)는 서버의 도구 목록을 보여주고 모델이 언제 이를 호출할지 결정하도록 합니다. 서버는 stdio를 통해 로컬 프로세스로 실행되거나 Streamable HTTP를 통해 원격 엔드포인트로 실행될 수 있습니다. 원격 서버가 더 최신 상태를 유지하기 쉽습니다. 왜냐하면 클라이언트가 배포되는 즉시 새로운 릴리스를 볼 수 있기 때문입니다.
저희가 확인한 React 컴포넌트 라이브러리 MCP 서버는 세 가지 형태가 있습니다. 2026년 10월 기준으로 비교해 드리겠습니다:
첫 번째 형태는 문서 조회(docs lookup)입니다. MUI와 React Suite는 npm 패키지를 배포하므로, 에이전트는 정확한 props와 작동하는 링크만 필요하며 소스 파일은 전혀 필요하지 않습니다. 만약 앱이 Material UI를 사용한다면, MUI 자체 서버가 적절한 선택입니다.
두 번째 형태는 레지스트리 설치기(registry installer)입니다. shadcn 문서는 components.json의 모든 shadcn 호환 레지스트리에서 항목을 나열하고 검색하며 설치하는 방법을 설명하지만, 디자인 규칙이나 업데이트 확인에 대해서는 언급하지 않습니다. 여러 레지스트리에서 가져올 경우, 하나의 shadcn 서버가 이들을 모두 커버하므로 이는 실제적인 장점입니다.
세 번째 형태는 소스-복사(source-copy) 라이브러리가 필요로 하는 것입니다. 즉, 문서화(docs), 설치 및 유지보수 기능을 하나의 서버에서 제공해야 합니다. 컴포넌트가 코드 형태로 저장소에 존재하여 편집할 수 있다면, 에이전트는 해당 라이브러리가 무엇을 제공하는지, 프로젝트가 어떤 버전을 사용하고 있는지, 그리고 라이브러리가 어떻게 사용되기를 기대하는지 알아야 합니다. 마지막 부분이 바로 props 테이블만으로는 담아낼 수 없는 정보입니다.
코딩 에이전트가 컴포넌트를 발명하는 이유?
모델은 학습 데이터로부터 작성하기 때문에, 이 학습 데이터는 라이브러리 버전보다 앞서 있으며 가장 일반적인 API에 치우쳐 있습니다. 이를 확인할 방법이 없다면, 에이전트는 모든 공백을 가장 가능성 높은 추측으로 채웁니다. 예를 들어, shadcn의 API를 사용하지 않는 라이브러리에 적용하거나, 두 메이저 버전 전에 이름이 바뀐 props를 사용하거나, 시맨틱 토큰이 들어가야 할 자리에 헥스 컬러(hex color)를 사용하는 식입니다.
monday.com 엔지니어링 팀은 How We Use AI to Turn Figma Designs into Production Code에서 동일한 실패 사례를 설명했습니다 (Rivka Ungar, 2026년 2월 2일). 그들의 첫 시도는 Figma MCP와 함께 Cursor에 붙여넣은 Figma 링크였는데, 이로 인해 색상이 하드코딩되고 디자인 시스템 컴포넌트를 건너뛴 코드가 생성되었습니다. 그들의 진단은
| Piece | 답변하는 내용 | 변경 빈도 | Wingo UI에서
| --- | --- | --- |
| MCP server | 존재하는 것, 그 props와 사용법, 디자인 규칙, 현재 버전 | 매 릴리스마다 | https://wingo-ui.com/mcp, 10개 도구 및 1개 프롬프트 |
| ... |
The split that matters: the rules file stays short and stable, and everything that changes lives behind the server. Prop tables pasted into a rules file go stale with the next release, and an agent tends to trust the copy already in its context over a tool it would have to call. Our rules file names tools and commands. It never lists a component's props.
컴포넌트 라이브러리 MCP 서버가 노출해야 할 도구는 무엇인가요?
에이전트가 UI를 구축할 때 수행하는 작업(찾기, 읽기, 규칙 따르기, 설치하기, 최신 상태 유지)을 중심으로 몇 가지 읽기 전용 도구가 있습니다. 저희의 도구는 총 열 개입니다:
search_components: 키워드를 통해 컴포넌트, 블록, 훅 및 헬퍼 찾기.list_categories: 항목 수와 함께 카테고리 탐색하기.get_component: props, 파트, 사용법, 의존성, 설치 명령어 및 소스 가져오기.get_block: 전체 화면 또는 섹션과 그것이 구성하는 컴포넌트 가져오기.get_design_rules: 토큰, 크기, 모션, 폼, 오버레이 및 모바일 규칙 가져오기.get_theme_tokens: 라이트 모드와 다크 모드를 위한 CSS 변수 가져오기.get_install_instructions: Next.js 또는 Vite용 프로젝트 설정 가져오기.check_updates: 설치된 항목과 최신 릴리스 비교하기.get_changelog: 최근 릴리스 및 관련 노트 가져오기.get_account_status: 계정에 Pro가 있는지 여부와 업그레이드 링크 가져오기.
또한, 에이전트에게 검색, 규칙, 설치 및 구성 과정을 안내하는 build_screen이라는 프롬프트도 있습니다. 모든 도구는 주석(annotations)에서 읽기 전용(read-only)이며 이상적(idempotent)으로 표시되어 있으며, 그중 어떤 것도 디스크에 쓰지 않습니다. 파일 작성은 CLI의 역할입니다.
검색은 슬러그와 각 항목당 한 줄을 반환해야 합니다
검색 결과는 에이전트가 한눈에 훑어볼 수 있는 짧은 목록입니다. 이것은 서버에서 search_components 함수를 'orders table with filters'라는 쿼리와 limit: 5로 요청하여 얻은 실제 답변이며, 처음 세 개의 결과를 잘라낸 것입니다:
5 results for "orders table with filters":
- **Data Table** `data-table` (component, pro, v1.1.0): TanStack Table v9의 관리자 테이블: 검색, 필터, 정렬, 일괄 작업, 고정, 크기 조정, 가상화 및 휴대폰용 카드.
...
각 결과는 슬러그(slug), 종류(kind), 접근 등급(access tier) 및 버전을 포함하며, 마지막 줄은 다음 도구의 이름을 명시하여 에이전트가 어떤 호출을 통해 슬러그를 props로 변환해야 할지 추측할 필요가 없게 합니다. 세 번째 결과는 약한 일치입니다. 괜찮습니다. 설명 한 줄만으로도 에이전트는 get_component 호출을 사용하여 알아낼 필요 없이 건너뛸 수 있습니다.
Props에 기본값이 필요합니다
get_component는 문서 페이지에서 보여주는 props 테이블, 타입 및 기본값 외에도 파츠(parts), 사용 예시, npm 및 레지스트리 의존성, 그리고 설치 명령을 반환합니다. 기본값은 생성된 코드를 간결하게 유지하는 요소입니다. Button의 기본값을 아는 에이전트는 `type=
대규모 응답은 클라이언트에서 하드 리밋에 부딪힙니다. 2026년 10월 기준으로, Claude Code의 MCP 문서에 따르면 도구 결과가 10,000 토큰을 초과하면 경고하고, 기본적으로 결과를 25,000 토큰으로 제한하며 (MAX_MCP_OUTPUT_TOKENS로 조정 가능), 50,000자를 초과하는 텍스트 결과는 컨텍스트에 넣지 않고 파일로 저장합니다.
저희의 Data Table은 3,940줄짜리 단일 파일이며, TypeScript 약 150KB입니다. 소스 코드를 제외한 문서만으로도 약 18,000자(대략 4,500 토큰)가 나옵니다. 여기에 소스 코드까지 첨부하면 (Pro 키 사용 시), 같은 호출이 160,000자를 넘어서 위의 모든 제한을 초과합니다. 따라서 에이전트에게, 그리고 이러한 서버 중 하나를 설계하는 누구에게나 규칙은 다음과 같습니다: MCP를 통해 문서를 가져오고(docs through MCP), 파일은 CLI를 통해 가져옵니다(files through the CLI). 대규모 항목의 경우 includeSource: false로 get_component를 호출하고, 코드는 npx wingo-ui@latest add가 작성하도록 하세요.
규칙도 마찬가지입니다. 주제(topic)를 all로 지정한 get_design_rules는 약 45,000자(일반적인 토큰당 네 글자를 기준으로 대략 11,000 토큰)가 반환되는데, 이는 이미 Claude Code의 경고선을 넘어섭니다. mobile 주제만으로도 약 1,900자이고, forms는 약 4,200자입니다. 필요한 작업이 요구하는 주제를 요청하세요.
오류 메시지는 다음에 무엇을 해야 할지 알려야 합니다
도구 오류(tool error)는 에이전트가 읽는 프롬프트이므로, 그처럼 작성해야 합니다. 알 수 없는 슬러그(slug)는 가장 가까운 일치 항목들을 응답하고 search_components로 다시 안내합니다. Pro 키 없이 요청된 Pro 항목은 문서와 함께 다음 내용을 그대로 응답합니다 (링크는 잘리고, 줄 바꿈됨):
Login Page는 Wingo UI Pro의 일부이며, 소스 코드는 이 호출자에게 포함되지 않았습니다.
(API 키 없음; https://wingo-ui.com/sign-in에서 무료 계정을 만들면 무료 항목을 사용할 수 있습니다).
문서만으로 재구축하지 마세요.
...
서버에서 가장 중요한 문장은 "문서(docs)를 보고 다시 만들지 마세요(Do not re-create it from the docs)"입니다. 방금 완전한 props 테이블과 긴 상호작용 설명을 읽은 에이전트는 재작성을 시도하는 데 필요한 모든 것을 갖추게 되며, 그 결과는 종이에만 맞는 반쪽짜리 복사본일 뿐입니다. 버전 기록도 없고, 업데이트도 없으며, 설명이 한 줄로 요약한 엣지 케이스(edge cases) 중 어느 것도 없습니다.
에이전트가 가장 먼저 읽는 것은 서버 지침입니다
Claude Code는 기본적으로 도구 검색(tool search)을 활성화하므로, 세션 시작 시에는 도구 이름과 각 서버의 지침만 로드됩니다. 전체 도구 정의는 모델이 해당 도구를 찾을 때 로드됩니다. 같은 문서에 따르면 Claude Code는 기본적으로 각 도구 설명과 각 서버의 지침을 2,048자에서 잘라냅니다. 이 지침은 서버가 모델에게 보내는 홍보 자료와 같습니다: 어떤 작업을 처리하는지, 언제 도구를 검색해야 하는지, 그리고 잘림(truncation)에도 살아남아야 할 규칙들입니다. 첫 몇 줄에 "UI를 작성하기 전에 검색하세요(search before you write UI)"라고 넣으세요.