heroui-v2-mcp

HeroUI v2 (https://v2.heroui.com) 컴포넌트 문서, 소스 코드, 스타일 정의 및 테마 토큰을 위한 MCP(Model Context Protocol) 서버입니다.

공식 @heroui/react-mcp — HeroUI v3를 대상으로 하며 배포된 Cloudflare Worker + R2 버킷 + PostHog 프로젝트를 필요로 합니다 — 와 달리, 이 프로젝트는 독립형 로컬 서버입니다: 프로세스가 살아 있는 동안 모든 것을 heroui-inc/heroui@main(v2.x를 추적하는 브랜치) 및 raw.githubusercontent.com에서 직접 요청하여 가져오고 결과를 메모리에 캐시합니다. 클라우드 계정, API 배포, 추출 파이프라인이 필요 없습니다.

별도 프로젝트를 만드는 이유

HeroUI v3(브랜치 v3, 사이트 heroui.com)와 v2(브랜치 main, 사이트 v2.heroui.com)는 서로 다른, 호환되지 않는 컴포넌트 모델입니다 — 패키지 구조가 다르고, v2 사이트에는 llms.txt가 없으며, 문서 폴더 구조(/docs/components/* vs /docs/react/*)가 다르고, 스타일링 방식(packages/core/theme/src/components 아래의 tailwind-variants 파일 vs v3가 사용하는 방식)도 다릅니다. 공식 MCP는 v2 문서를 제공하지 않겠다고 명시적으로 거부하므로, 이 프로젝트는 도구 구성은 동일하게 유지하되 v2 데이터 소스를 가리킵니다.

Related MCP server: UI Toolkit MCP Server

도구

설치 및 실행

이 패키지는 npm에 heroui-v2-mcp로 게시되어 있으므로, 사용하기 위해 클론하거나 빌드할 필요가 없습니다.

Claude Code / Claude Desktop / Cursor에서 사용하기

MCP 설정에 추가하세요 — npx가 요청 시 다운로드하여 실행합니다:

{
  "mcpServers": {
    "heroui-v2": {
      "command": "npx",
      "args": ["-y", "heroui-v2-mcp"]
    }
  }
}

또는 전역으로 설치한 뒤 바이너리를 직접 지정하세요:

npm install -g heroui-v2-mcp

{
  "mcpServers": {
    "heroui-v2": {
      "command": "heroui-v2-mcp"
    }
  }
}

로컬 개발 (소스에서)

npm install
npm run dev         # tsx --watch, runs src/server.ts directly (no build step)
npm run inspect      # launches @modelcontextprotocol/inspector against src/server.ts
npm run build        # emits dist/server.js

GitHub 속도 제한

디렉터리 목록은 GitHub REST API를 통해 가져오는데, 인증하지 않으면 시간당 60회 요청으로 제한됩니다. 파일 내용(raw.githubusercontent.com)은 이 제한에 적용되지 않습니다. 여러 컴포넌트를 탐색하다가 403 오류가 발생하면 토큰을 설정하세요:

export GITHUB_TOKEN=ghp_xxx   # no scopes needed, just raises the rate limit to 5000/hr

데이터 해석 방식

• 컴포넌트 목록 = main 브랜치의 apps/docs/content/docs/components/*.mdx 파일들.

• 대부분의 문서 slug는 packages/components/<slug> 패키지에 1:1로 매핑됩니다. 소수의 문서 페이지는 다른 패키지에 번들로 포함된 하위 컴포넌트를 설명합니다(예: textarea는 @heroui/input 안에, checkbox-group은 @heroui/checkbox 안에 있음) — src/constants.ts의 COMPONENT_PACKAGE_ALIASES를 참조하세요.

• Props/API 테이블은 각 .mdx 문서 페이지에 포함된 <APITable data={[...]} /> JSX 리터럴에서 파싱됩니다(해당 배열은 JS 리터럴로 평가됩니다 — 공식 저장소의 정적 데이터이며, 임의의/신뢰할 수 없는 입력이 아닙니다).

• 테마 토큰은 packages/core/theme/src/colors/{semantic,common}.ts 및 default-layout.ts에서 가져옵니다.

캐싱

모든 GitHub 응답(파일 내용 또는 디렉터리 목록)은 30분 동안 메모리에 캐시됩니다(src/constants.ts의 CACHE_TTL_MS). 더 빨리 새로고침하려면 프로세스를 다시 시작하세요.