# Palette MCP Server - 개발 플로우
## 전체 워크플로우
```
┌──────────────────────────────────────────────────────────────────────────┐
│ Figma to Code 워크플로우 │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. 디자이너 2. 개발자 3. AI 도구 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Figma │ ──URL─▶ │ Cursor │ ──요청──▶ │ Palette │ │
│ │ Design │ │ │ │ MCP │ │
│ └─────────┘ └─────────┘ └────┬────┘ │
│ │ │
│ ▼ │
│ 4. 결과 ┌─────────┐ │
│ ┌─────────┐ │ Figma │ │
│ │ React/ │ ◀──변환─── │ API │ │
│ │ Vue │ └─────────┘ │
│ │ 코드 │ │
│ └─────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────┘
```
---
## 상세 데이터 플로우
### 1단계: Figma 데이터 가져오기
```
사용자 입력
│
▼
┌─────────────────────────────────────┐
│ Figma URL 파싱 │
│ - 파일 ID 추출 │
│ - node-id 추출 (선택적) │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ FigmaService.getFigmaData() │
│ │
│ ┌─────────────────────────────┐ │
│ │ MCP 클라이언트 연결 시도 │ │
│ │ (Figma Desktop MCP) │ │
│ └──────────┬──────────────────┘ │
│ │ │
│ 성공? ├──── 예 ──▶ MCP 데이터 │
│ │ │
│ 아니오 ▼ │
│ ┌──────────────────────────────┐ │
│ │ REST API 폴백 │ │
│ │ (FIGMA_ACCESS_TOKEN 사용) │ │
│ └──────────────────────────────┘ │
└────────────────┬────────────────────┘
│
▼
FigmaFile 객체
```
### 2단계: 컴포넌트 매핑
```
FigmaFile.document (노드 트리)
│
▼
┌─────────────────────────────────────┐
│ mapFigmaToDesignSystem() │
│ │
│ 각 노드에 대해: │
│ 1. 노드 타입 확인 (TEXT, FRAME 등) │
│ 2. 노드 이름 분석 │
│ 3. 자식 구조 분석 │
│ 4. 최적 컴포넌트 매칭 │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 매핑 결과 │
│ │
│ { │
│ figmaNode: FigmaNode, │
│ designSystemComponent: Component, │
│ confidence: 0.8 │
│ }[] │
└─────────────────────────────────────┘
```
### 3단계: 코드 생성
```
매핑 결과
│
▼
┌─────────────────────────────────────┐
│ generateReactComponent() / │
│ generateVueComponent() │
│ │
│ 1. Import 문 수집 │
│ - 사용된 컴포넌트별 import 생성 │
│ │
│ 2. JSX/Template 생성 │
│ - 노드 트리 순회 │
│ - 컴포넌트 렌더링 │
│ - Props 생성 │
│ - 중첩 최소화 │
│ │
│ 3. 컴포넌트 구조 래핑 │
│ - interface 정의 │
│ - export 추가 │
└────────────────┬────────────────────┘
│
▼
생성된 코드 문자열
```
### 4단계: 파일 저장 및 프리뷰
```
생성된 코드
│
▼
┌─────────────────────────────────────┐
│ generateAndSaveReactComponent() │
│ │
│ 1. 요청 ID 생성 (UUID) │
│ 2. 폴더 생성 │
│ palette-output/{requestId}/ │
│ │
│ 3. 파일 저장 │
│ - ComponentName.tsx │
│ - ComponentName.html (옵션) │
│ - ComponentName.png (옵션) │
│ - metadata.json │
└─────────────────────────────────────┘
```
---
## 컴포넌트 동기화 플로우
서버 시작 시 GitHub에서 최신 디자인 시스템 컴포넌트 정보를 동기화합니다.
```
서버 시작
│
▼
┌─────────────────────────────────────┐
│ DesignSystemService.initialize() │
│ │
│ autoSync: true (기본값) │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ ComponentSyncService.sync() │
│ │
│ 1. 캐시 확인 │
│ └── 유효? ──▶ 캐시 데이터 반환 │
│ │
│ 2. GitHub API 호출 │
│ - ssm-web 저장소 접근 │
│ - design-system-react 패키지 │
│ - design-system 패키지 │
│ │
│ 3. TypeScript 파일 분석 │
│ - AST 파싱 │
│ - Props 인터페이스 추출 │
│ - 컴포넌트 메타데이터 생성 │
│ │
│ 4. 캐시 저장 │
└────────────────┬────────────────────┘
│
▼
컴포넌트 메타데이터 업데이트
```
---
## 사용자 요청 처리 플로우
### convert_figma_to_react 요청
```
┌─────────────────────────────────────────────────────────────────┐
│ MCP 클라이언트 (Cursor) │
│ │
│ 요청: │
│ { │
│ "method": "tools/call", │
│ "params": { │
│ "name": "convert_figma_to_react", │
│ "arguments": { │
│ "figmaUrl": "https://figma.com/design/xxx?node-id=1-2", │
│ "componentName": "ProductCard", │
│ "previewType": "both" │
│ } │
│ } │
│ } │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Palette MCP Server │
│ │
│ 1. Figma URL에서 파일 ID, node-id 추출 │
│ 2. FigmaService로 데이터 가져오기 │
│ 3. CodeGenerator로 React 코드 생성 │
│ 4. 파일 저장 (코드, HTML, 이미지) │
│ 5. 결과 반환 │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 응답: │
│ { │
│ "content": [ │
│ { │
│ "type": "text", │
│ "text": "# React Component Generated\n\n..." │
│ }, │
│ { │
│ "type": "image", │
│ "data": "base64...", │
│ "mimeType": "image/png" │
│ } │
│ ] │
│ } │
└─────────────────────────────────────────────────────────────────┘
```
---
## 에러 처리 플로우
```
요청 처리 중 에러 발생
│
▼
┌────────────────────────────┐
│ 에러 타입 확인 │
└─────────┬──────────────────┘
│
├── Figma 접근 에러
│ └── MCP 실패 → REST API 폴백
│ └── REST 실패 → 에러 응답
│
├── 컴포넌트 매핑 실패
│ └── 기본 컴포넌트(Button) 폴백
│ 또는 div 컨테이너 사용
│
├── 코드 생성 에러
│ └── 에러 메시지와 함께 응답
│
└── 이미지 생성 에러
└── 경고 로그 후 계속 진행
(이미지 없이 코드만 반환)
```
---
## 로컬 개발 플로우
```bash
# 1. 의존성 설치
yarn install
# 2. 환경 변수 설정
cp .env.example .env
# .env 파일에 FIGMA_ACCESS_TOKEN 설정
# 3. 개발 서버 실행
yarn dev
# 4. MCP Inspector로 테스트
npx @anthropic-ai/mcp-inspector ./dist/index.js
# 5. Cursor에서 테스트
# ~/.cursor/mcp.json에 서버 설정 추가
```
---
## 배포 플로우
### npm 배포
```bash
# 1. 빌드
yarn build
# 2. 버전 업데이트
npm version patch # 또는 minor, major
# 3. npm 배포
npm publish
```
### Smithery.ai 배포
```yaml
# smithery.yaml
startCommand:
type: stdio
configSchema:
type: object
properties:
figmaAccessToken:
type: string
description: Figma Personal Access Token
```
Smithery에서 자동으로 빌드 및 배포됩니다.
