# Palette MCP Server - 사용법 및 설정 가이드
## 빠른 시작
### 방법 1: Smithery.ai에서 설치 (권장)
1. [Smithery.ai](https://smithery.ai)에서 `palette-mcp` 검색
2. "Install" 클릭
3. 환경 변수 입력:
- `FIGMA_ACCESS_TOKEN`: Figma API 토큰 (필수)
- `GITHUB_TOKEN`: GitHub 토큰 (선택)
### 방법 2: Cursor에서 수동 설치
`~/.cursor/mcp.json` 파일에 다음 추가:
```json
{
"mcpServers": {
"palette": {
"type": "stdio",
"command": "npx",
"args": ["-y", "palette-mcp"],
"env": {
"FIGMA_ACCESS_TOKEN": "YOUR_FIGMA_TOKEN_HERE"
}
}
}
}
```
### 방법 3: 로컬 개발 환경
```bash
# 저장소 클론
git clone https://github.com/Opti-kjh/palette.git
cd palette
# 의존성 설치
yarn install
# 환경 설정
cp .env.example .env
# .env 파일에 FIGMA_ACCESS_TOKEN 추가
# 개발 모드 실행
yarn dev
```
---
## 환경 변수 설정
### 필수 설정
| 변수명 | 설명 | 발급 방법 |
|--------|------|-----------|
| `FIGMA_ACCESS_TOKEN` | Figma Personal Access Token | Figma → Settings → Personal Access Tokens |
### 선택 설정
| 변수명 | 설명 | 기본값 |
|--------|------|--------|
| `GITHUB_TOKEN` | GitHub API 토큰 (컴포넌트 동기화용) | - |
| `FIGMA_MCP_SERVER_URL` | Figma Desktop MCP 서버 URL | `http://127.0.0.1:3845/mcp` |
| `USE_FIGMA_MCP` | MCP 클라이언트 사용 여부 | `true` |
### Figma Access Token 발급 방법
1. [Figma](https://www.figma.com) 접속
2. 우측 상단 프로필 → Settings
3. Account 탭 → Personal Access Tokens
4. "Generate new token" 클릭
5. 토큰 이름 입력 후 생성
6. 생성된 토큰 복사 (한 번만 표시됨)
---
## Cursor에서 사용하기
### 기본 사용법
Figma에서 디자인을 선택하고 "Copy link to selection"으로 URL 복사 후:
```
https://www.figma.com/design/akI7EwlWemAf8KJup9F2ZS/...?node-id=45733-32370
를 React 코드로 작성해줘
```
또는 더 구체적으로:
```
이 Figma 디자인을 ProductCard라는 이름의 React 컴포넌트로 변환해줘:
https://www.figma.com/design/xxx?node-id=123-456
```
### 프롬프트 예시
#### React 컴포넌트 생성
```
Figma URL: https://www.figma.com/design/xxx?node-id=123-456
이 디자인을 LoginForm이라는 React 컴포넌트로 변환해줘.
디자인 시스템 컴포넌트를 활용해서 만들어줘.
```
#### Vue 컴포넌트 생성
```
이 Figma 디자인을 Vue 컴포넌트로 변환해줘:
https://www.figma.com/design/xxx?node-id=123-456
컴포넌트 이름: UserProfile
```
#### 디자인 시스템 컴포넌트 조회
```
디자인 시스템에서 사용 가능한 React 컴포넌트 목록을 보여줘
```
#### Figma 파일 분석
```
이 Figma 파일의 구조를 분석해줘:
https://www.figma.com/design/xxx
```
---
## MCP Tools 상세 가이드
### 1. convert_figma_to_react
Figma 디자인을 React 컴포넌트로 변환합니다.
**파라미터:**
| 파라미터 | 필수 | 설명 |
|----------|------|------|
| `figmaUrl` | O | Figma 파일 URL 또는 파일 ID |
| `componentName` | O | 생성될 컴포넌트 이름 (예: ProductCard) |
| `nodeId` | X | 특정 노드 ID (URL에 포함되어 있으면 생략 가능) |
| `previewType` | X | 미리보기 타입: `html`, `image`, `both` (기본값: `both`) |
**출력:**
- React TSX 컴포넌트 코드
- HTML 미리보기 파일 (선택적)
- PNG 스크린샷 (선택적)
- 메타데이터 JSON
**예시:**
```json
{
"name": "convert_figma_to_react",
"arguments": {
"figmaUrl": "https://www.figma.com/design/xxx?node-id=123-456",
"componentName": "ProductCard",
"previewType": "both"
}
}
```
### 2. convert_figma_to_vue
Figma 디자인을 Vue 3 SFC로 변환합니다.
**파라미터:**
| 파라미터 | 필수 | 설명 |
|----------|------|------|
| `figmaUrl` | O | Figma 파일 URL 또는 파일 ID |
| `componentName` | O | 생성될 컴포넌트 이름 |
| `nodeId` | X | 특정 노드 ID |
| `previewType` | X | 미리보기 타입 |
### 3. list_design_system_components
사용 가능한 디자인 시스템 컴포넌트 목록을 조회합니다.
**파라미터:**
| 파라미터 | 필수 | 설명 |
|----------|------|------|
| `framework` | O | `react` 또는 `vue` |
**예시:**
```json
{
"name": "list_design_system_components",
"arguments": {
"framework": "react"
}
}
```
### 4. analyze_figma_file
Figma 파일 구조를 분석합니다.
**파라미터:**
| 파라미터 | 필수 | 설명 |
|----------|------|------|
| `figmaUrl` | O | Figma 파일 URL |
**출력:**
- 총 노드 수
- 컴포넌트 수
- 프레임 수
- 텍스트 요소 수
- 사용 가능한 컴포넌트 목록
- 추천 컴포넌트 매핑
---
## 생성된 코드 구조
### React 컴포넌트 예시
```tsx
// Design System Components from GitHub:
// React: https://github.com/dealicious-inc/ssm-web/tree/master/packages/design-system-react
import { Button } from '@dealicious/design-system-react/src/components/ssm-button';
import { Text } from '@dealicious/design-system-react/src/components/ssm-text';
import { Tag } from '@dealicious/design-system-react/src/components/ssm-tag';
import React from 'react';
interface ProductCardProps {
// Add your props here
}
const ProductCard: React.FC<ProductCardProps> = (props) => {
return (
<div>
<Text variant="heading" size="large">
상품명
</Text>
<Tag variant="primary">
신상품
</Tag>
<Button size="medium">
구매하기
</Button>
</div>
);
};
export default ProductCard;
```
### Vue 컴포넌트 예시
```vue
<template>
<div>
<SsmText variant="heading" size="large">
상품명
</SsmText>
<SsmTag variant="primary">
신상품
</SsmTag>
<SsmButton size="medium">
구매하기
</SsmButton>
</div>
</template>
<script setup lang="ts">
import SsmButton from '@dealicious/design-system/src/components/ssm-button';
import SsmText from '@dealicious/design-system/src/components/ssm-text';
import SsmTag from '@dealicious/design-system/src/components/ssm-tag';
// Add your reactive data and methods here
</script>
<style scoped>
/* Add your styles here */
</style>
```
---
## 문제 해결
### 자주 발생하는 문제
#### 1. "FIGMA_ACCESS_TOKEN을 찾을 수 없습니다"
**원인:** 환경 변수가 설정되지 않음
**해결:**
- `.env` 파일에 `FIGMA_ACCESS_TOKEN` 추가
- Cursor mcp.json의 `env` 섹션에 토큰 추가
- Smithery 설정에서 토큰 입력
#### 2. "Figma API error"
**원인:** 토큰이 잘못되었거나 권한이 없음
**해결:**
- 토큰이 올바른지 확인
- Figma에서 토큰 재발급
- 파일에 대한 접근 권한 확인
#### 3. MCP 서버 연결 실패
**원인:** Figma Desktop 앱이 실행되지 않음
**해결:**
- Figma Desktop 앱 실행
- MCP 플러그인 활성화 확인
- REST API 폴백 사용 (자동)
#### 4. 이미지 생성 실패
**원인:** Puppeteer 미설치 또는 의존성 문제
**해결:**
- 이미지 없이 계속 진행 (자동)
- Puppeteer 수동 설치: `npm install puppeteer`
---
## 개발 명령어
```bash
# 의존성 설치
yarn install
# 빌드
yarn build
# 개발 모드 (hot reload)
yarn dev
# MCP 서버 실행
yarn start
yarn mcp
# 테스트
yarn test
yarn test:services
yarn test:figma-tools
yarn test:mcp-servers
# 디자인 시스템 동기화
yarn sync:ds
# MCP Inspector로 테스트
npx @anthropic-ai/mcp-inspector ./dist/index.js
```
---
## 추가 리소스
- **GitHub 저장소**: [Opti-kjh/palette](https://github.com/Opti-kjh/palette)
- **npm 패키지**: [@anthropic/palette-mcp](https://www.npmjs.com/package/@anthropic/palette-mcp)
- **Smithery**: [smithery.ai](https://smithery.ai)에서 `palette-mcp` 검색
- **MCP 프로토콜 문서**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **디자인 시스템**: [ssm-web GitHub](https://github.com/dealicious-inc/ssm-web)
