GDS MCP

Levit 디자인 시스템(GDS) 메타데이터를 AI 코딩 도구(Claude Code, Cursor 등)에 노출하는 MCP 서버입니다.

신규 입사자나 AI 에이전트가 "우리 GDS에 어떤 색상이 있어?", "이 #F7F8F9 무슨 토큰이야?", "Badge 어떻게 써야 해?" 같은 질문을 했을 때, 항상 최신 디자인 시스템 정의를 기준으로 답하게 만드는 것이 목표입니다.

제공 도구

Tool	시나리오
list_color_tokens	"컬러 토큰 어떤 게 있어?" — 전체 목록(이름·값·설명)
get_color_token	"gray-10 값이 뭐야?" — 이름으로 단건 조회
find_token_by_value	"이 #F7F8F9 무슨 토큰이야?" — hex 역검색 (표기 차이 흡수)
get_component_usage	"Badge 어떻게 써?" — 컴포넌트 사용 규칙 + 스펙

find_token_by_value는 #FFF / #FFFFFF / 대소문자 / # 유무를 정규화해서 비교하므로, 디자인 시안이나 코드에서 발견한 hex를 그대로 넣어도 매칭됩니다.

동작 방식

서버(src/index.ts)는 data/design-system.json을 읽기만 합니다. 그 파일은 scripts/extract-metadata.ts가 디자인 시스템의 실제 소스 (Figma 변수 export 또는 Style Dictionary 산출물)로부터 생성합니다.

GDS 토큰 수정 → release 발행 → CI에서 extract + build → GitHub Packages publish → 팀원은 npx로 최신 실행

로컬 개발

pnpm install
pnpm dev      # tsx로 서버 직접 실행
pnpm build    # dist/ 생성

Node 버전은 .node-version(22)에 고정돼 있습니다. fnm/mise/nvm 모두 이 파일을 읽어 자동으로 버전을 맞춥니다. 패키지 매니저는 packageManager 필드로 pnpm에 고정됩니다.

토큰 소스 연결 (TODO)

scripts/extract-metadata.ts의 TOKENS_SOURCE 경로를 실제 GDS 빌드 산출물로 교체하면 됩니다. Style Dictionary 트리({ color: { gray: { "10": { value, comment } } } })를 gray-10 형태로 평탄화하는 변환이 포함되어 있습니다. 소스가 연결되기 전까지는 data/design-system.json의 샘플 값으로 동작합니다.

팀원 사용법

private 패키지이므로 read:packages 스코프를 가진 personal access token이 필요합니다. 홈 디렉토리 ~/.npmrc:

@supin-kim-ilevit-com:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<개인 PAT>

MCP 클라이언트 설정(예: Claude Code):

{
  "mcpServers": {
    "gds": {
      "command": "npx",
      "args": ["-y", "@supin-kim-ilevit-com/gds-mcp"]
    }
  }
}