Claude Code 및 Cursor가 실제로 사용할 수 있는 shadcn/ui 레지스트리 구축 방법

대부분의 shadcn/ui 컴포넌트는 이제 사람이 명령어를 입력하는 것이 아니라 AI 코딩 에이전트에 의해 설치됩니다. 만약 레지스트리를 게시한다면, 그 에이전트가 사용자입니다. 이 에이전트는 사용자의 컴포넌트를 찾아내고, 추측 없이 해당 컴포넌트의 props를 읽어내며, 올바른 설치 명령을 실행할 수 있어야 합니다. 단순히 문서를 클릭하는 사람만을 위한 레지스트리는 오용될 가능성이 높습니다.

저는 shadcn/ui 레지스트리인 HextaUI를 운영하고 있으며, 올해 많은 시간을 들여 Claude Code, Cursor 및 shadcn MCP 서버가 사용할 수 있도록 만들었습니다. 제가 다시 할 것이 있다면, 중요하다고 생각하는 순서대로 정리했습니다.

1. 유효성 검사를 통과하는 레지스트리 배포하기

기본부터 시작해야 합니다. 모든 항목은 name, type, files, dependencies, 그리고 registryDependencies를 포함하며, 레지스트리 스키마를 따르는 JSON 파일이어야 합니다. 인덱스는 안정적인 URL에, 각 항목은 예측 가능한 URL에 배치하세요:

shadcn build을 실행하여 registry.json 소스에서 이를 생성하고 배포하기 전에 유효성 검사를 수행해야 합니다. CLI는 2026년 5월에 레지스트리 유효성 검사 단계를 추가했습니다. 유효성 검사에 실패하는 레지스트리는 에이전트에게 조용히 실패하며, 이 경우 에이전트는 컴포넌트를 수동으로 작성하여 잘못된 결과를 얻게 됩니다.

실질적인 차이를 만드는 두 가지 세부 사항이 있습니다:

완전한 URL을 사용하는 registryDependencies. Dialog가 Button에 의존하는 경우, button 대신 https://your-site.com/r/button.json을 지정해야 합니다. 그렇지 않으면 CLI는 shadcn/ui의 Button을 가져옵니다.
모든 것에 의존하는 all.json 항목.

설치 페이지와 llms.txt에 이 스니펫을 문서화하세요. 짧은 형태(short form)가 shadcn MCP 서버가 검색하는 것이므로, 네임스페이스가 없는 레지스트리는 에이전트들이 레지스트리를 탐색하는 데 사용하는 가장 중요한 도구에게는 보이지 않습니다.

레지스트리가 비공개인 경우, 객체 형태(object form)는 CLI가 확장하고 기록하지 않는 환경 변수를 가진 헤더를 사용합니다:

{
  "registries": {
    "@acme-pro": {
...

3. 모든 문서 페이지에 Markdown 쌍을 제공하세요

에이전트는 HTML을 제대로 가져오지 못합니다. 마크다운(Markdown)은 잘 가져옵니다. 모든 문서 URL이 설명, 설치 명령어, 전체 소스, 사용법, 예제, 키보드 지원 및 API 테이블과 동일한 내용으로 .md로 응답하도록 만드세요.

https://hextaui.com/docs/button      -> 사람을 위한 HTML
https://hextaui.com/docs/button.md   -> 에이전트를 위한 Markdown

마크다운은 직접 작성하지 마세요. 페이지와 동일한 소스에서 생성하여 두 가지가 절대 어긋나지 않게 하세요. HextaUI의 경우, .md 경로는 페이지의 React 트리를 순회하며 직렬화하므로, 페이지에 예제를 추가하면 마크다운에도 자동으로 추가됩니다.

API 참조가 여기서 가장 중요합니다. props 테이블을 읽을 수 있는 에이전트는 존재하지 않는 size="xl"을 환각(hallucinate)하지 않습니다.

4. llms.txt와 llms-full.txt를 게시하세요

llms.txt는 사이트 루트에 있는 마크다운 인덱스입니다: 프로젝트가 무엇인지, 언제 사용해야 하는지, 언제 사용하면 안 되는지, 어떻게 설치하는지, 그리고 문서 페이지마다 .md 링크와 함께 한 줄씩 기록합니다. llms-full.txt는 모든 문서 페이지를 연결한 것으로, 모든 것을 한 번에 로드하고 싶은 에이전트를 위한 것입니다.

AI 에이전트를 위한 서비스 발견 가능성 및 API 개선 방법

저는 https://hextaui.com/mcp에서 두 번째 서버를 실행합니다. 이 서버는 Streamable HTTP 방식이며, 읽기 전용이고 API 키가 필요 없으며, 다음 다섯 가지 도구(search_docs, get_component, get_component_api, get_examples, get_install_command)를 갖추고 있습니다. Claude Code는 한 줄의 명령어로 연결합니다:

claude mcp add --transport http hextaui https://hextaui.com/mcp

Cursor와 VS Code는 동일한 URL을 MCP 설정에 사용합니다. 일단 연결되면, "비동기 결과를 갖춘 HextaUI 콤보박스 추가"라는 요청은 문서 검색, API 읽기, 그리고 올바른 설치 명령으로 변환되며 그 사이에 추측 과정이 없습니다.

발견 가능하도록 만드세요. /.well-known/mcp/server-card.json에 서버 카드를 게시하고 MCP 레지스트리 형식으로 server.json을 추가하세요. 에이전트와 주변 도구들은 가장 먼저 그곳을 찾아보기 시작할 것입니다.

6. OpenAPI를 사용하여 HTTP 인터페이스 및 실제 오류 설명하기

위의 모든 것은 일반 HTTP이며, 에이전트들은 직접 HTTP를 호출하는 경우가 점점 늘어나고 있습니다. 작업 ID(operation ids)와 타입 지정된 응답(typed responses)을 포함하여 openapi.json을 게시하세요. 다음 작업을 수행해야 하는지 알려주는 resolution 필드를 갖는 RFC 9457 application/problem+json 형식으로 오류를 반환하세요:

{
  "type": "https://hextaui.com/docs/api#not-found",
  "title": "컴포넌트를 찾을 수 없음",
...

힌트와 함께 404 응답을 받는 에이전트는 복구합니다. HTML 오류 페이지를 받는 에이전트는 메모리에서 컴포넌트를 작성합니다.

7. 스킬 파일 배포하기

Claude Code와 증가하는 목록의 에이전트들은 도구를 사용하는 방법을 설명하는 SKILL.md 파일을 읽습니다. 다음 경로에 하나를 배치하세요: /.well-known/agent-skills/<name>/SKILL.md. 이 파일에는 컴포넌트를 찾고, 문서를 읽고, 설치하는 방법과 정확한 명령어가 포함되어야 합니다. 이것은 마크다운(Markdown) 페이지이며 사이트에서 가장 높은 레버리지를 가진 페이지입니다.

8. 자신으로 테스트하지 말고 에이전트로 테스트하기

MCP 서버가 연결된 상태이고 다른 컨텍스트가 없는 새 Next.js 프로젝트를 Claude Code에서 열어보세요. "범위와 비활성화된 주말 규칙을 갖춘 날짜 선택기 추가"라고 요청해 보세요. 그것이 무엇을 하는지 지켜보세요. 잘못 추측하는 모든 것은 여러분의 .md 문서나 llms.txt에 존재하는 격차입니다.

그 다음으로 Cursor에서도 llms.txt만 사용하고 MCP는 사용하지 않은 방식으로 동일하게 진행합니다. 그리고 URL만 가지고도 작동해야 합니다. 이 레지스트리는 세 가지 방식 모두에서 우아하게(gracefully) 기능이 저하되어야 합니다.

이것을 통해 얻게 되는 것들

MCP 서버 또는 .md 문서가 연결된 에이전트는 속성표(props table)를 추측하는 대신 읽고, 컴포넌트를 재작성하는 대신 설치 명령을 실행하며, 의존성을 올바른 순서로 설치합니다. HextaUI의 레지스트리 측면은 일주일 정도의 작업이 소요되었습니다. 에이전트 측면이 더 오래 걸렸으며, 이것이 현재 대부분의 설치 작업을 수행하는 사람들에게 이 레지스트리를 사용 가능하게 만든 부분입니다.

모든 것을 라이브로 보고 싶다면: hextaui.com/llms.txt, .md가 추가된 모든 문서 페이지, MCP 문서, 그리고 OpenAPI spec이 포함된 API 문서를 확인하세요.

FAQ

shadcn CLI가 MCP 서버를 가지고 있다면, 저도 자체 MCP 서버가 필요한가요? shadcn MCP는 components.json에서 레지스트리 전반의 검색 및 설치를 다룹니다. 사용자 본인의 서버는 문서(docs), API, 그리고 예시를 다룹니다. 대부분의 레지스트리는 둘 다 혜택을 받습니다.

MCP 서버가 API 키를 요구해야 하나요? 공개 문서는 그렇지 않습니다. 필요한 모든 키는 포기하는 에이전트입니다. 인증은 비공개 항목에만 적용하고, components.json 헤더를 통해 bearer 토큰을 사용하세요.

콘텐츠 중복 없이 Markdown 문서를 생성하려면 어떻게 해야 하나요? 페이지가 사용하는 것과 동일한 컴포넌트 트리를 렌더링하고 이를 Markdown으로 직렬화(serialize)하면 됩니다. 하나의 소스에서 두 가지 형식입니다.

llms.txt에는 무엇을 넣어야 하나요? 설명, 언제 사용해야 하는지 그리고 사용하지 말아야 하는지, 설치 명령, 네임스페이스 스니펫, 그리고 .md에 연결되는 문서 페이지당 한 줄이 들어갑니다.