# GDS MCP

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

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

## 제공 도구

| Tool | 시나리오 |
| --- | --- |
| `list_color_tokens` | "컬러 토큰 어떤 게 있어?" — 전체 목록(이름·값·설명) |
| `get_color_token` | "Cool Gray/50 값이 뭐야?" — 이름으로 단건 조회 |
| `find_token_by_value` | "이 #30333d 무슨 토큰이야?" — hex 역검색 (표기 차이 흡수) |
| `list_tokens` | "spacing 토큰 뭐 있어?" — color·spacing·typography·effect 등 토큰 통합 목록 |
| `get_token` | "SP-04 값이 뭐야?" — 카테고리/이름으로 토큰 단건 조회 |
| `search_design_system` | "Cool Gray, SP-04, Label 관련 뭐 있어?" — 토큰·컴포넌트·가이드라인 통합 검색 |
| `list_components` | "컴포넌트 뭐 있어?" — 컴포넌트 목록 |
| `get_component_usage` | "이 컴포넌트 어떻게 써?" — 확인된 사용 규칙, props, flat/compound 코드 패턴 |
| `get_component_code_usage` | "Button 코드로 어떻게 써?" — import 상태, props 기반 flat pattern, 조립형 compound pattern |
| `list_guidelines` | "가이드 문서 뭐 있어?" — 가이드라인 목록 |
| `get_guideline` | "색상 대비 가이드 보여줘" — 가이드라인 단건 조회 |

`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로 최신 실행
```

## 로컬 개발

```bash
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`입니다.

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

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

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

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

```bash
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):

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