palette-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Palette
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# Palette MCP
+
+Figma 디자인을 기존 Design System 컴포넌트를 활용하여 React/Vue 코드로 변환하는 MCP(Model Context Protocol) 서버입니다.
+
+[![Smithery](https://img.shields.io/badge/Smithery-Install-blue)](https://smithery.ai/server/@anthropic/palette-mcp)
+[![npm version](https://img.shields.io/npm/v/@anthropic/palette-mcp.svg)](https://www.npmjs.com/package/@anthropic/palette-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🚀 빠른 시작
+
+### Smithery.ai에서 설치 (권장)
+
+1. [Smithery.ai](https://smithery.ai)에서 `palette-mcp` 검색
+2. "Install" 클릭
+3. 환경 변수 입력:
+   - `FIGMA_ACCESS_TOKEN`: Figma API 토큰 (필수)
+   - `GITHUB_TOKEN`: GitHub 토큰 (선택, 디자인 시스템 접근용)
+
+### Cursor에서 수동 설치
+
+`~/.cursor/mcp.json` 파일에 다음 추가:
+
+```json
+{
+  "mcpServers": {
+    "palette": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@anthropic/palette-mcp"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": "YOUR_FIGMA_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+### 환경 변수
+
+| 변수명 | 필수 | 설명 |
+|--------|------|------|
+| `FIGMA_ACCESS_TOKEN` | ✅ | Figma Personal Access Token |
+| `GITHUB_TOKEN` | ❌ | GitHub 토큰 (디자인 시스템 패키지 접근용) |
+| `FIGMA_MCP_SERVER_URL` | ❌ | Figma MCP 서버 URL (기본값: http://127.0.0.1:3845/mcp) |
+
+#### Figma Access Token 발급:
+1. [Figma](https://www.figma.com) → Settings → Account
+2. Personal Access Tokens → Generate new token
+
+---
+
+## 📖 사용법
+
+### Cursor에서 사용
+
+Figma에서 디자인을 선택하고 "Copy link to selection"으로 URL을 복사한 후:
+
+```
+https://www.figma.com/design/akI7EwlWemAf8KJup9F2ZS/...?node-id=45733-32370 
+를 React 코드로 작성해줘
+```
+
+### 지원하는 명령
+
+| 명령 | 설명 |
+|------|------|
+| `convert_figma_to_react` | Figma 디자인을 React 컴포넌트로 변환 |
+| `convert_figma_to_vue` | Figma 디자인을 Vue 컴포넌트로 변환 |
+| `list_design_system_components` | 사용 가능한 디자인 시스템 컴포넌트 목록 |
+| `analyze_figma_file` | Figma 파일 구조 분석 |
+
+---
+
+## 🎨 지원하는 Design System 컴포넌트
+
+### React Components (`@dealicious/design-system-react`)
+
+| 카테고리 | 컴포넌트 |
+|----------|----------|
+| **Actions** | Button, TextLink |
+| **Forms** | Input, Check, Radio, Switch, Dropdown, TextField |
+| **Data Display** | Text, Tag, Chip, Badge, LabeledText |
+| **Feedback** | Toast, Notice, Error, LoadingSpinner, Tooltip |
+| **Navigation** | Tab, Pagination, ArrowPagination, Accordion |
+| **Overlays** | LayerPopup, LayerAlert |
+
+### Vue Components (`@dealicious/design-system`)
+
+| 카테고리 | 컴포넌트 |
+|----------|----------|
+| **Actions** | SsmButton, SsmTextLink |
+| **Forms** | SsmInput, SsmCheck, SsmSwitch, SsmDropdown |
+| **Data Display** | SsmText, SsmTag, SsmChip, SsmBadge |
+| **Navigation** | SsmTab, SsmPagination, SsmAccordion |
+
+---
+
+## 🔧 로컬 개발
+
+### 설치
+
+```bash
+git clone https://github.com/Opti-kjh/palette.git
+cd palette
+yarn install
+```
+
+### 환경 설정
+
+```bash
+cp .env.example .env
+# .env 파일에 FIGMA_ACCESS_TOKEN 추가
+```
+
+### 빌드 및 실행
+
+```bash
+# 빌드
+yarn build
+
+# 개발 모드
+yarn dev
+
+# MCP 서버 실행
+yarn mcp
+```
+
+### 테스트
+
+```bash
+# MCP Inspector로 테스트
+npx @anthropic-ai/mcp-inspector ./dist/index.js
+```
+
+---
+
+## 📁 프로젝트 구조
+
+```
+src/
+├── index.ts                 # MCP 서버 메인 파일
+├── services/
+│   ├── figma.ts            # Figma API 연동
+│   ├── design-system.ts    # 디자인 시스템 메타데이터
+│   └── code-generator.ts   # React/Vue 코드 생성
+└── utils/
+    ├── figma-mcp-client.ts # Figma MCP 클라이언트
+    └── request-manager.ts  # 요청 관리
+```
+
+---
+
+## ⚠️ 중요: 디자인 시스템 사용 원칙
+
+이 MCP 서버는 **항상 디자인 시스템 컴포넌트를 사용**합니다.
+
+- ❌ Tailwind CSS 사용 금지
+- ❌ 일반 HTML/CSS 사용 금지
+- ✅ 디자인 시스템 컴포넌트만 사용
+
+---
+
+## 🤝 기여
+
+이슈 및 PR은 [GitHub](https://github.com/Opti-kjh/palette)에서 환영합니다.
+
+## 📄 라이선스
+
+MIT License - [LICENSE](./LICENSE) 참조

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+// .env 파일 로드
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// 프로젝트 루트의 .env 파일 로드
+dotenv.config({ path: join(__dirname, '..', '.env') });
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { readFile } from 'fs/promises';
+import { FigmaService } from './services/figma.js';
+import { DesignSystemService } from './services/design-system.js';
+import { CodeGenerator } from './services/code-generator.js';
+// MCP 서버 초기화
+const server = new Server({
+    name: 'palette',
+    version: '1.0.0',
+});
+// Figma 및 Design System 서비스 초기화
+const figmaService = new FigmaService();
+const designSystemService = new DesignSystemService();
+const codeGenerator = new CodeGenerator(designSystemService);
+// 사용 가능한 도구 목록
+const tools = [
+    {
+        name: 'convert_figma_to_react',
+        description: 'Convert Figma design to React component using existing design system',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                figmaUrl: {
+                    type: 'string',
+                    description: 'Figma file URL or file ID',
+                },
+                nodeId: {
+                    type: 'string',
+                    description: 'Specific node ID to convert (optional)',
+                },
+                componentName: {
+                    type: 'string',
+                    description: 'Name for the generated component',
+                },
+                previewType: {
+                    type: 'string',
+                    enum: ['html', 'image', 'both'],
+                    description: 'Preview type: "html" for HTML file, "image" for PNG image, "both" for both (default: "both")',
+                    default: 'both',
+                },
+            },
+            required: ['figmaUrl', 'componentName'],
+        },
+    },
+    {
+        name: 'convert_figma_to_vue',
+        description: 'Convert Figma design to Vue component using existing design system',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                figmaUrl: {
+                    type: 'string',
+                    description: 'Figma file URL or file ID',
+                },
+                nodeId: {
+                    type: 'string',
+                    description: 'Specific node ID to convert (optional)',
+                },
+                componentName: {
+                    type: 'string',
+                    description: 'Name for the generated component',
+                },
+                previewType: {
+                    type: 'string',
+                    enum: ['html', 'image', 'both'],
+                    description: 'Preview type: "html" for HTML file, "image" for PNG image, "both" for both (default: "both")',
+                    default: 'both',
+                },
+            },
+            required: ['figmaUrl', 'componentName'],
+        },
+    },
+    {
+        name: 'list_design_system_components',
+        description: 'List available components in the design system',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                framework: {
+                    type: 'string',
+                    enum: ['react', 'vue'],
+                    description: 'Framework to list components for',
+                },
+            },
+            required: ['framework'],
+        },
+    },
+    {
+        name: 'analyze_figma_file',
+        description: 'Analyze Figma file structure and available components',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                figmaUrl: {
+                    type: 'string',
+                    description: 'Figma file URL or file ID',
+                },
+            },
+            required: ['figmaUrl'],
+        },
+    },
+];
+// 도구 목록 핸들러
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools };
+});
+// 도구 실행 핸들러
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'convert_figma_to_react': {
+                const { figmaUrl, nodeId, componentName, previewType = 'both' } = args;
+                const figmaData = await figmaService.getFigmaData(figmaUrl, nodeId);
+                const files = await codeGenerator.generateAndSaveReactComponent(figmaData, componentName, figmaUrl, nodeId, previewType);
+                // 결과 메시지 구성
+                let fileList = `- 컴포넌트: \`${files.componentFile}\`\n`;
+                if (files.htmlFile) {
+                    fileList += `- HTML 미리보기: \`${files.htmlFile}\`\n`;
+                }
+                if (files.imageFile) {
+                    fileList += `- 이미지 미리보기: \`${files.imageFile}\`\n`;
+                }
+                fileList += `- 메타데이터: \`${files.metadataFile}\``;
+                const content = [
+                    {
+                        type: 'text',
+                        text: `# React Component Generated\n\n**요청 ID:** \`${files.requestId}\`\n**저장 경로:** \`${files.folderPath}\`\n\n## 생성된 파일\n${fileList}\n\n## 컴포넌트 코드\n\n\`\`\`tsx\n${await readFile(files.componentFile, 'utf-8')}\n\`\`\``,
+                    },
+                ];
+                // 이미지가 있으면 이미지도 포함
+                if (files.imageFile) {
+                    try {
+                        const imageBuffer = await readFile(files.imageFile);
+                        content.push({
+                            type: 'image',
+                            data: imageBuffer.toString('base64'),
+                            mimeType: 'image/png'
+                        });
+                    }
+                    catch (error) {
+                        console.warn('이미지 읽기 실패:', error);
+                    }
+                }
+                return { content };
+            }
+            case 'convert_figma_to_vue': {
+                const { figmaUrl, nodeId, componentName, previewType = 'both' } = args;
+                const figmaData = await figmaService.getFigmaData(figmaUrl, nodeId);
+                const files = await codeGenerator.generateAndSaveVueComponent(figmaData, componentName, figmaUrl, nodeId, previewType);
+                // 결과 메시지 구성
+                let fileList = `- 컴포넌트: \`${files.componentFile}\`\n`;
+                if (files.htmlFile) {
+                    fileList += `- HTML 미리보기: \`${files.htmlFile}\`\n`;
+                }
+                if (files.imageFile) {
+                    fileList += `- 이미지 미리보기: \`${files.imageFile}\`\n`;
+                }
+                fileList += `- 메타데이터: \`${files.metadataFile}\``;
+                const content = [
+                    {
+                        type: 'text',
+                        text: `# Vue Component Generated\n\n**요청 ID:** \`${files.requestId}\`\n**저장 경로:** \`${files.folderPath}\`\n\n## 생성된 파일\n${fileList}\n\n## 컴포넌트 코드\n\n\`\`\`vue\n${await readFile(files.componentFile, 'utf-8')}\n\`\`\``,
+                    },
+                ];
+                // 이미지가 있으면 이미지도 포함
+                if (files.imageFile) {
+                    try {
+                        const imageBuffer = await readFile(files.imageFile);
+                        content.push({
+                            type: 'image',
+                            data: imageBuffer.toString('base64'),
+                            mimeType: 'image/png'
+                        });
+                    }
+                    catch (error) {
+                        console.warn('이미지 읽기 실패:', error);
+                    }
+                }
+                return { content };
+            }
+            case 'list_design_system_components': {
+                const { framework } = args;
+                const components = await designSystemService.getAvailableComponents(framework);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `# Available ${framework} Components\n\n${components
+                                .map((comp) => `- **${comp.name}**: ${comp.description}`)
+                                .join('\n')}`,
+                        },
+                    ],
+                };
+            }
+            case 'analyze_figma_file': {
+                const { figmaUrl } = args;
+                const analysis = await figmaService.analyzeFigmaFile(figmaUrl);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `# Figma File Analysis\n\n${analysis}`,
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// 서버 시작
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Palette server running on stdio');
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});

package/dist/services/code-generator.d.ts

@@ -0,0 +1,121 @@
+import { FigmaFile } from './figma.js';
+import { DesignSystemService } from './design-system.js';
+export interface GeneratedComponent {
+    name: string;
+    code: string;
+    imports: string[];
+    dependencies: string[];
+}
+export type PreviewType = 'html' | 'image' | 'both';
+export interface GeneratedFiles {
+    requestId: string;
+    folderPath: string;
+    componentFile: string;
+    htmlFile?: string;
+    imageFile?: string;
+    metadataFile: string;
+}
+export declare class CodeGenerator {
+    private designSystemService;
+    constructor(designSystemService: DesignSystemService);
+    /**
+     * Figma 데이터에서 React 컴포넌트 생성
+     */
+    generateReactComponent(figmaData: FigmaFile, componentName: string): Promise<string>;
+    /**
+     * HTML을 렌더링하여 이미지로 변환
+     */
+    private generateImagePreview;
+    /**
+     * React 컴포넌트 생성 및 파일 저장
+     */
+    generateAndSaveReactComponent(figmaData: FigmaFile, componentName: string, figmaUrl: string, nodeId?: string, previewType?: PreviewType): Promise<GeneratedFiles>;
+    /**
+     * Figma 데이터에서 Vue 컴포넌트 생성
+     */
+    generateVueComponent(figmaData: FigmaFile, componentName: string): Promise<string>;
+    /**
+     * Vue 컴포넌트 생성 및 파일 저장
+     */
+    generateAndSaveVueComponent(figmaData: FigmaFile, componentName: string, figmaUrl: string, nodeId?: string, previewType?: PreviewType): Promise<GeneratedFiles>;
+    /**
+     * HTML 미리보기 파일 생성
+     */
+    private generateHTMLPreview;
+    /**
+     * HTML 이스케이프
+     */
+    private escapeHtml;
+    /**
+     * Figma 노드를 디자인 시스템 컴포넌트에 매핑
+     */
+    private mapFigmaToDesignSystem;
+    /**
+     * 단일 Figma 노드 분석 및 디자인 시스템 최적 매칭 찾기
+     * 항상 디자인 시스템 컴포넌트를 반환 - null이 아님
+     */
+    private analyzeNode;
+    /**
+     * Figma 노드 속성에 따라 디자인 시스템 컴포넌트 찾기
+     * 노드 타입, 이름, 구조, 속성을 종합적으로 분석하여 적절한 컴포넌트 매핑
+     */
+    private findComponentByNodeProperties;
+    /**
+     * FRAME 노드 분석 - 자식 구조를 기반으로 적절한 컴포넌트 선택
+     */
+    private analyzeFrameNode;
+    /**
+     * 노드가 버튼 레이블인지 확인
+     */
+    private isButtonLabel;
+    /**
+     * 노드가 링크의 일부인지 확인
+     */
+    private hasLinkParent;
+    /**
+     * 기본 디자인 시스템 컴포넌트 가져오기
+     */
+    private getDefaultComponent;
+    /**
+     * 노드 유형에 따라 기본 컴포넌트 가져오기
+     * findComponentByNodeProperties에서 매칭되지 않은 경우에만 사용
+     */
+    private getDefaultComponentByType;
+    /**
+     * React 컴포넌트 구조 생성
+     */
+    private generateReactComponentStructure;
+    /**
+     * Vue 컴포넌트 구조 생성
+     */
+    private generateVueComponentStructure;
+    /**
+     * Figma 노드에서 React JSX 생성
+     * 불필요한 중첩을 제거하여 깊이를 최소화
+     */
+    private generateReactJSX;
+    /**
+     * 컴포넌트가 단순 컨테이너 역할만 하는지 확인
+     */
+    private isSimpleContainer;
+    /**
+     * Figma 노드에서 Vue 템플릿 생성
+     */
+    private generateVueTemplate;
+    /**
+     * Figma 노드와 디자인 시스템 컴포넌트에 따라 컴포넌트 속성 생성
+     */
+    private generateComponentProps;
+    /**
+     * Figma 노드에 대한 적절한 HTML 태그 이름 가져오기
+     */
+    private getHTMLTagName;
+    /**
+     * Figma 노드에서 CSS 클래스 이름 생성
+     */
+    private generateClassName;
+    /**
+     * Figma 노드 속성에서 인라인 스타일 생성
+     */
+    private generateInlineStyle;
+}