GDS MCP

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

신규 입사자나 AI 에이전트가 "우리 GDS에 어떤 색상이 있어?", "이 #30333d 무슨 토큰이야?", "SP-04 값이 뭐야?" 같은 질문을 했을 때, 항상 Figma에 실제 정의된 디자인 시스템 기준으로 답하게 만드는 것이 목표입니다.

제공 도구

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

Related MCP server: grocers-design-mcp

동작 방식

서버(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/ 생성
pnpm run validate:metadata
pnpm run smoke # build 이후 MCP stdio smoke test

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

실제 Figma 토큰 소스 연결

원칙: Figma에서 확인되지 않은 토큰은 data/design-system.json에 넣지 않습니다. 예시나 추정값도 토큰 데이터로 저장하지 않습니다.

토큰은 아래 우선순위로 추출합니다.

1. FIGMA_TOKEN + FIGMA_FILE_KEY: Figma Variables REST API에서 직접 조회

2. FIGMA_VARIABLES_FILE: Figma Variables API 응답 JSON 파일

3. TOKENS_SOURCE: Tokens Studio 또는 Style Dictionary JSON 파일

Figma API를 직접 쓰려면 personal access token에 file_variables:read scope가 필요합니다. Figma 공식 문서 기준으로 로컬 변수 조회 엔드포인트는 GET /v1/files/:file_key/variables/local입니다.

FIGMA_TOKEN=<figma_pat> FIGMA_FILE_KEY=<file_key> pnpm run extract
pnpm run build

API 접근 권한이 없거나 Enterprise 플랜 제한에 걸리면 Variables API 응답을 파일로 받아서 동일한 변환을 실행할 수 있습니다.

FIGMA_VARIABLES_FILE=./fixtures/figma-variables.json pnpm run extract

Style Dictionary 또는 Tokens Studio export를 쓰는 경우:

TOKENS_SOURCE=../gds/dist/tokens.json pnpm run extract

Figma Variables API는 COLOR를 tokens.color, FLOAT를 tokens.spacing 또는 tokens.number, STRING을 tokens.string, BOOLEAN을 tokens.boolean으로 분류합니다. SP-*, spacing, gap, padding, margin, radius, corner 계열 이름/collection/scope는 spacing으로 분류합니다. 소스가 연결되기 전까지는 Figma에서 이미 확인된 기존 값만 유지합니다.

컴포넌트/가이드라인 연결

컴포넌트 사용 규칙과 가이드라인은 아직 자동 추출 대상이 아니므로, Figma나 별도 공식 문서에서 확인된 항목만 data/design-system.json의 components, guidelines에 유지합니다. 실제 Figma 컴포넌트를 연결할 때는 각 컴포넌트 또는 Component Set의 node URL을 기준으로 props, variants, usage, 예시를 확인해서 이 JSON에 반영합니다.

개발자가 "실제로 코드로 어떻게 써?"라고 물었을 때 답할 수 있도록 각 컴포넌트에는 선택적으로 codeUsage를 둡니다. 여기에는 확정된 props, 구현 매핑 상태, flat pattern, compound pattern 예시를 넣습니다. 단, Figma에서 component property로 확인되지 않은 API는 확정값처럼 쓰지 않고 "구현체와 매핑 필요" 상태로 분리합니다.

codeUsage는 디자이너 구현 가이드가 아니라 실제 소비처에서 GDS를 가져다 쓰는 방법을 우선합니다. 응답 우선순위는 다음 순서입니다.

1. recommendedUsage: 실제 페이지에서 가장 먼저 써야 하는 API

2. prerequisites: Provider, CSS import, overlay root 같은 전제 조건

3. api: 실제 export/props/hook 시그니처

4. whenToUse / avoid: 언제 쓰고 무엇을 피해야 하는지

5. flatPattern / compoundPattern: 복붙 가능한 예시

6. sourceRefs: 기준이 된 실제 코드 파일

단순 컴포넌트는 direct-component로 분류하고 직접 렌더링 예시를 우선합니다. Toast처럼 overlay lifecycle이 중요한 컴포넌트는 overlay-hook-first로 분류하고 useRewardToast, useTextToast 같은 훅 사용법을 직접 컴포넌트 렌더링보다 먼저 안내합니다.

importPath는 실제 UI 컴포넌트 패키지의 export가 확인된 뒤에만 확정합니다. 현재 이 repo는 MCP 서버 패키지이므로, 실제 UI 패키지나 소스 repo에서 export가 확인되지 않은 컴포넌트 import 경로는 임의로 만들지 않습니다. pattaya의 @wetripod/game-design-system에서 확인된 컴포넌트는 해당 export 기준으로 importPath를 확정합니다.

팀원 사용법

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"]
    }
  }
}