palette-mcp 1.1.1 → 1.2.0

package/dist/server.d.ts

@@ -5,10 +5,25 @@
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { type SyncConfig } from './services/design-system.js';
 export interface ServerConfig {
     figmaAccessToken?: string;
     githubToken?: string;
     figmaMcpServerUrl?: string;
+    /**
+     * Figma Desktop MCP 클라이언트 사용 여부
+     * Remote 모드(Smithery)에서는 false로 설정해야 함 (로컬호스트 접근 불가)
+     */
+    useFigmaMcp?: boolean;
+    /**
+     * 디자인 시스템 컴포넌트 동기화 설정
+     */
+    syncConfig?: SyncConfig;
+    /**
+     * 인증 건너뛰기 (로컬 개발용)
+     * true로 설정하면 GitHub 조직 멤버십 확인을 건너뜁니다.
+     */
+    skipAuth?: boolean;
 }
 export declare const tools: Tool[];
 /**

package/dist/server.js

@@ -4,35 +4,43 @@
  * Local(stdio) 모드와 Remote(Smithery) 모드에서 공유되는 핵심 기능을 정의합니다.
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } 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';
-// Tools 정의
+import { validateAccess } from './services/auth.js';
+// Tools 정의 (annotations 포함)
 export const tools = [
     {
         name: 'convert_figma_to_react',
-        description: 'Figma 디자인을 디자인 시스템을 사용하여 React 컴포넌트로 변환합니다',
+        description: 'Figma 디자인을 @dealicious/design-system-react 컴포넌트를 사용하여 React 컴포넌트로 변환합니다. Figma 파일 URL과 컴포넌트 이름을 제공하면, 디자인 시스템 컴포넌트(Button, Text, Tag, Check, Chip 등)를 활용한 React TSX 코드를 생성합니다.',
+        annotations: {
+            title: 'Figma to React Converter',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         inputSchema: {
             type: 'object',
             properties: {
                 figmaUrl: {
                     type: 'string',
-                    description: 'Figma 파일 URL 또는 파일 ID',
+                    description: 'Figma 파일의 전체 URL (예: https://www.figma.com/file/ABC123/Design?node-id=1-2) 또는 파일 ID',
                 },
                 nodeId: {
                     type: 'string',
-                    description: '변환할 특정 노드 ID (선택사항)',
+                    description: '변환할 특정 Figma 노드의 ID. URL에 node-id가 포함되어 있으면 생략 가능합니다.',
                 },
                 componentName: {
                     type: 'string',
-                    description: '생성할 컴포넌트 이름',
+                    description: '생성될 React 컴포넌트의 이름 (예: ProductCard, LoginForm)',
                 },
                 previewType: {
                     type: 'string',
                     enum: ['html', 'image', 'both'],
-                    description: '미리보기 타입: "html"은 HTML 파일, "image"는 PNG 이미지, "both"는 둘 다 (기본값: "both")',
+                    description: '미리보기 생성 옵션: "html"은 브라우저에서 볼 수 있는 HTML 파일, "image"는 PNG 스크린샷, "both"는 둘 다 생성 (기본값: "both")',
                     default: 'both',
                 },
             },
@@ -41,26 +49,33 @@ export const tools = [
     },
     {
         name: 'convert_figma_to_vue',
-        description: 'Figma 디자인을 디자인 시스템을 사용하여 Vue 컴포넌트로 변환합니다',
+        description: 'Figma 디자인을 @dealicious/design-system Vue 컴포넌트를 사용하여 Vue 3 Single File Component로 변환합니다. Figma 파일 URL과 컴포넌트 이름을 제공하면, 디자인 시스템 컴포넌트를 활용한 Vue SFC 코드를 생성합니다.',
+        annotations: {
+            title: 'Figma to Vue Converter',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         inputSchema: {
             type: 'object',
             properties: {
                 figmaUrl: {
                     type: 'string',
-                    description: 'Figma 파일 URL 또는 파일 ID',
+                    description: 'Figma 파일의 전체 URL (예: https://www.figma.com/file/ABC123/Design?node-id=1-2) 또는 파일 ID',
                 },
                 nodeId: {
                     type: 'string',
-                    description: '변환할 특정 노드 ID (선택사항)',
+                    description: '변환할 특정 Figma 노드의 ID. URL에 node-id가 포함되어 있으면 생략 가능합니다.',
                 },
                 componentName: {
                     type: 'string',
-                    description: '생성할 컴포넌트 이름',
+                    description: '생성될 Vue 컴포넌트의 이름 (예: ProductCard, LoginForm)',
                 },
                 previewType: {
                     type: 'string',
                     enum: ['html', 'image', 'both'],
-                    description: '미리보기 타입: "html"은 HTML 파일, "image"는 PNG 이미지, "both"는 둘 다 (기본값: "both")',
+                    description: '미리보기 생성 옵션: "html"은 브라우저에서 볼 수 있는 HTML 파일, "image"는 PNG 스크린샷, "both"는 둘 다 생성 (기본값: "both")',
                     default: 'both',
                 },
             },
@@ -69,14 +84,21 @@ export const tools = [
     },
     {
         name: 'list_design_system_components',
-        description: '디자인 시스템에서 사용 가능한 컴포넌트 목록을 조회합니다',
+        description: '@dealicious/design-system에서 사용 가능한 모든 UI 컴포넌트 목록을 조회합니다. 각 컴포넌트의 이름, 설명, import 경로, 사용 가능한 props를 반환합니다.',
+        annotations: {
+            title: 'Design System Component List',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {
             type: 'object',
             properties: {
                 framework: {
                     type: 'string',
                     enum: ['react', 'vue'],
-                    description: '컴포넌트를 조회할 프레임워크',
+                    description: '컴포넌트를 조회할 프레임워크: "react"는 design-system-react, "vue"는 design-system 패키지',
                 },
             },
             required: ['framework'],
@@ -84,19 +106,76 @@ export const tools = [
     },
     {
         name: 'analyze_figma_file',
-        description: 'Figma 파일 구조와 사용 가능한 컴포넌트를 분석합니다',
+        description: 'Figma 파일의 구조를 분석하여 페이지, 프레임, 컴포넌트 계층을 파악합니다. 변환하기 전에 파일 구조를 이해하는 데 유용합니다.',
+        annotations: {
+            title: 'Figma File Analyzer',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         inputSchema: {
             type: 'object',
             properties: {
                 figmaUrl: {
                     type: 'string',
-                    description: 'Figma 파일 URL 또는 파일 ID',
+                    description: '분석할 Figma 파일의 전체 URL 또는 파일 ID',
                 },
             },
             required: ['figmaUrl'],
         },
     },
 ];
+// Prompts 정의
+const prompts = [
+    {
+        name: 'convert-design-to-component',
+        description: 'Figma 디자인을 React 또는 Vue 컴포넌트로 변환하는 가이드 프롬프트',
+        arguments: [
+            {
+                name: 'figmaUrl',
+                description: 'Figma 파일 URL',
+                required: true,
+            },
+            {
+                name: 'framework',
+                description: '프레임워크 선택 (react 또는 vue)',
+                required: true,
+            },
+            {
+                name: 'componentName',
+                description: '컴포넌트 이름',
+                required: true,
+            },
+        ],
+    },
+    {
+        name: 'explore-design-system',
+        description: '디자인 시스템 컴포넌트 탐색 가이드',
+        arguments: [
+            {
+                name: 'framework',
+                description: '프레임워크 선택 (react 또는 vue)',
+                required: false,
+            },
+        ],
+    },
+];
+// Resources 정의
+const resources = [
+    {
+        uri: 'palette://design-system/react/components',
+        name: 'React Design System Components',
+        description: '@dealicious/design-system-react에서 사용 가능한 컴포넌트 목록',
+        mimeType: 'application/json',
+    },
+    {
+        uri: 'palette://design-system/vue/components',
+        name: 'Vue Design System Components',
+        description: '@dealicious/design-system에서 사용 가능한 컴포넌트 목록',
+        mimeType: 'application/json',
+    },
+];
 /**
  * MCP 서버를 생성하고 핸들러를 등록합니다.
  * Local 모드와 Remote 모드에서 공통으로 사용됩니다.
@@ -112,23 +191,59 @@ export function createPaletteServer(config = {}) {
     if (config.figmaMcpServerUrl) {
         process.env.FIGMA_MCP_SERVER_URL = config.figmaMcpServerUrl;
     }
-    // MCP 서버 초기화
+    // MCP 서버 초기화 (모든 capabilities 활성화)
     const server = new Server({
         name: 'palette',
         version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {}, // tools 기능 활성화
+            prompts: {}, // prompts 기능 활성화
+            resources: {}, // resources 기능 활성화
+        },
     });
     // 서비스 초기화
-    const figmaService = new FigmaService();
-    const designSystemService = new DesignSystemService();
+    // Remote 모드에서는 Figma Desktop MCP 클라이언트를 사용하지 않음 (로컬호스트 접근 불가)
+    const useFigmaMcp = config.useFigmaMcp !== undefined ? config.useFigmaMcp : true;
+    const figmaService = new FigmaService(useFigmaMcp, config.figmaMcpServerUrl);
+    const designSystemService = new DesignSystemService(config.syncConfig);
     const codeGenerator = new CodeGenerator(designSystemService);
-    // 도구 목록 핸들러
+    // 인증 상태 캐시
+    let authResult = null;
+    /**
+     * 도구 실행 전 인증 확인
+     * skipAuth가 true이면 인증을 건너뜁니다.
+     */
+    async function ensureAuthenticated() {
+        // 로컬 개발 모드에서는 인증 건너뛰기
+        if (config.skipAuth) {
+            console.error('[Palette Auth] ⚠️ 인증 건너뛰기 모드 (skipAuth=true)');
+            return;
+        }
+        // 이미 인증되었으면 건너뛰기
+        if (authResult?.authorized) {
+            return;
+        }
+        // 인증 수행
+        const githubToken = config.githubToken || process.env.GITHUB_TOKEN;
+        authResult = await validateAccess(githubToken);
+        if (!authResult.authorized) {
+            throw new Error(authResult.error || '인증에 실패했습니다.');
+        }
+    }
+    // 디자인 시스템 컴포넌트 비동기 초기화 (백그라운드에서 실행)
+    designSystemService.initialize().catch((error) => {
+        console.error('[Palette] 디자인 시스템 초기화 실패:', error);
+    });
+    // ===== Tools 핸들러 =====
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         return { tools };
     });
-    // 도구 실행 핸들러
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
         try {
+            // 🔐 도구 실행 전 인증 확인
+            await ensureAuthenticated();
             switch (name) {
                 case 'convert_figma_to_react': {
                     const { figmaUrl, nodeId, componentName, previewType = 'both' } = args;
@@ -242,5 +357,83 @@ export function createPaletteServer(config = {}) {
             };
         }
     });
+    // ===== Prompts 핸들러 =====
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        return { prompts };
+    });
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        switch (name) {
+            case 'convert-design-to-component': {
+                const figmaUrl = args?.figmaUrl || '<FIGMA_URL>';
+                const framework = args?.framework || 'react';
+                const componentName = args?.componentName || 'MyComponent';
+                return {
+                    description: 'Figma 디자인을 컴포넌트로 변환하는 프롬프트',
+                    messages: [
+                        {
+                            role: 'user',
+                            content: {
+                                type: 'text',
+                                text: `Figma 디자인을 ${framework} 컴포넌트로 변환해주세요.\n\n- Figma URL: ${figmaUrl}\n- 컴포넌트 이름: ${componentName}\n\n디자인 시스템 컴포넌트를 최대한 활용해주세요.`,
+                            },
+                        },
+                    ],
+                };
+            }
+            case 'explore-design-system': {
+                const framework = args?.framework || 'react';
+                return {
+                    description: '디자인 시스템 탐색 프롬프트',
+                    messages: [
+                        {
+                            role: 'user',
+                            content: {
+                                type: 'text',
+                                text: `@dealicious/design-system${framework === 'react' ? '-react' : ''} 패키지에서 사용 가능한 컴포넌트 목록을 보여주세요. 각 컴포넌트의 사용법과 예제도 함께 알려주세요.`,
+                            },
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown prompt: ${name}`);
+        }
+    });
+    // ===== Resources 핸들러 =====
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return { resources };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        switch (uri) {
+            case 'palette://design-system/react/components': {
+                const components = await designSystemService.getAvailableComponents('react');
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: 'application/json',
+                            text: JSON.stringify(components, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'palette://design-system/vue/components': {
+                const components = await designSystemService.getAvailableComponents('vue');
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: 'application/json',
+                            text: JSON.stringify(components, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown resource: ${uri}`);
+        }
+    });
     return server;
 }

package/dist/services/auth.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 인증 및 권한 검증 서비스
+ *
+ * dealicious-inc 조직 멤버십을 확인하여 서비스 접근을 제어합니다.
+ */
+export interface AuthResult {
+    authorized: boolean;
+    username?: string;
+    organization?: string;
+    error?: string;
+}
+/**
+ * GitHub 조직 멤버십을 확인하여 서비스 접근 권한을 검증합니다.
+ *
+ * @param githubToken GitHub Personal Access Token
+ * @returns 인증 결과
+ */
+export declare function validateAccess(githubToken?: string): Promise<AuthResult>;
+/**
+ * 인증 캐시 초기화 (테스트용)
+ */
+export declare function clearAuthCache(): void;

package/dist/services/auth.js

@@ -0,0 +1,138 @@
+/**
+ * 인증 및 권한 검증 서비스
+ *
+ * dealicious-inc 조직 멤버십을 확인하여 서비스 접근을 제어합니다.
+ */
+import { Octokit } from '@octokit/rest';
+// 허용된 GitHub 조직 목록
+const ALLOWED_ORGANIZATIONS = ['dealicious-inc'];
+// 인증 상태 캐시 (토큰별로 검증 결과를 캐시)
+const authCache = new Map();
+// 캐시 유효 시간 (1시간)
+const CACHE_TTL_MS = 60 * 60 * 1000;
+/**
+ * GitHub 토큰으로 사용자 정보 조회
+ */
+async function getAuthenticatedUser(octokit) {
+    const { data } = await octokit.users.getAuthenticated();
+    return { login: data.login, email: data.email };
+}
+/**
+ * 사용자가 허용된 조직의 멤버인지 확인
+ */
+async function checkOrganizationMembership(octokit, org) {
+    try {
+        await octokit.orgs.getMembershipForAuthenticatedUser({ org });
+        return true;
+    }
+    catch (error) {
+        // 404: 멤버가 아님, 403: 권한 없음
+        if (error.status === 404 || error.status === 403) {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * 캐시된 인증 결과 확인
+ */
+function getCachedAuth(githubToken) {
+    const cached = authCache.get(githubToken);
+    if (!cached)
+        return null;
+    // 캐시 만료 확인
+    const now = new Date();
+    if (now.getTime() - cached.checkedAt.getTime() > CACHE_TTL_MS) {
+        authCache.delete(githubToken);
+        return null;
+    }
+    return { valid: cached.valid, username: cached.username };
+}
+/**
+ * 인증 결과 캐시 저장
+ */
+function setCachedAuth(githubToken, valid, username) {
+    authCache.set(githubToken, { valid, username, checkedAt: new Date() });
+}
+/**
+ * GitHub 조직 멤버십을 확인하여 서비스 접근 권한을 검증합니다.
+ *
+ * @param githubToken GitHub Personal Access Token
+ * @returns 인증 결과
+ */
+export async function validateAccess(githubToken) {
+    // GITHUB_TOKEN이 없으면 거부
+    if (!githubToken) {
+        return {
+            authorized: false,
+            error: 'GITHUB_TOKEN이 필요합니다. dealicious-inc 조직 멤버만 Palette MCP를 사용할 수 있습니다.',
+        };
+    }
+    // 캐시 확인
+    const cached = getCachedAuth(githubToken);
+    if (cached) {
+        if (cached.valid) {
+            return {
+                authorized: true,
+                username: cached.username,
+                organization: ALLOWED_ORGANIZATIONS[0],
+            };
+        }
+        else {
+            return {
+                authorized: false,
+                username: cached.username,
+                error: `사용자 '${cached.username}'은(는) dealicious-inc 조직 멤버가 아닙니다.`,
+            };
+        }
+    }
+    // GitHub API로 검증
+    const octokit = new Octokit({ auth: githubToken });
+    try {
+        // 사용자 정보 조회
+        const user = await getAuthenticatedUser(octokit);
+        // 조직 멤버십 확인
+        for (const org of ALLOWED_ORGANIZATIONS) {
+            const isMember = await checkOrganizationMembership(octokit, org);
+            if (isMember) {
+                // 캐시 저장
+                setCachedAuth(githubToken, true, user.login);
+                console.error(`[Palette Auth] ✅ 인증 성공: ${user.login} (${org})`);
+                return {
+                    authorized: true,
+                    username: user.login,
+                    organization: org,
+                };
+            }
+        }
+        // 어떤 조직에도 속하지 않음
+        setCachedAuth(githubToken, false, user.login);
+        console.error(`[Palette Auth] ❌ 인증 실패: ${user.login} - 허용된 조직 멤버 아님`);
+        return {
+            authorized: false,
+            username: user.login,
+            error: `사용자 '${user.login}'은(는) dealicious-inc 조직 멤버가 아닙니다. 조직 관리자에게 문의하세요.`,
+        };
+    }
+    catch (error) {
+        // 토큰 유효성 검사 실패
+        if (error.status === 401) {
+            return {
+                authorized: false,
+                error: 'GITHUB_TOKEN이 유효하지 않습니다. 토큰을 확인해주세요.',
+            };
+        }
+        // 기타 오류
+        console.error('[Palette Auth] 인증 중 오류 발생:', error.message);
+        return {
+            authorized: false,
+            error: `인증 중 오류가 발생했습니다: ${error.message}`,
+        };
+    }
+}
+/**
+ * 인증 캐시 초기화 (테스트용)
+ */
+export function clearAuthCache() {
+    authCache.clear();
+}

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

@@ -24,6 +24,7 @@ export declare class CodeGenerator {
     generateReactComponent(figmaData: FigmaFile, componentName: string): Promise<string>;
     /**
      * HTML을 렌더링하여 이미지로 변환
+     * puppeteer가 없으면 빈 문자열 반환
      */
     private generateImagePreview;
     /**

package/dist/services/code-generator.js

@@ -1,5 +1,23 @@
 import { saveFile, saveBinaryFile, saveMetadata, generateRequestId, getRequestFolderPath } from '../utils/request-manager.js';
-import puppeteer from 'puppeteer';
+// puppeteer는 optional dependency로, 없으면 이미지 프리뷰 기능이 비활성화됨
+let puppeteer = null;
+let puppeteerLoaded = false;
+/**
+ * puppeteer를 lazy loading으로 로드
+ */
+async function loadPuppeteer() {
+    if (puppeteerLoaded)
+        return puppeteer;
+    try {
+        puppeteer = (await import('puppeteer')).default;
+    }
+    catch (e) {
+        console.warn('puppeteer를 로드할 수 없습니다. 이미지 프리뷰 기능이 비활성화됩니다.');
+        puppeteer = null;
+    }
+    puppeteerLoaded = true;
+    return puppeteer;
+}
 export class CodeGenerator {
     designSystemService;
     constructor(designSystemService) {
@@ -44,9 +62,17 @@ export class CodeGenerator {
     }
     /**
      * HTML을 렌더링하여 이미지로 변환
+     * puppeteer가 없으면 빈 문자열 반환
      */
     async generateImagePreview(htmlContent, componentName, requestId) {
-        const browser = await puppeteer.launch({
+        // puppeteer를 lazy loading으로 로드
+        const pptr = await loadPuppeteer();
+        // puppeteer가 없으면 이미지 생성 불가
+        if (!pptr) {
+            console.warn('puppeteer가 설치되지 않아 이미지 프리뷰를 생성할 수 없습니다.');
+            return '';
+        }
+        const browser = await pptr.launch({
             headless: true,
             args: ['--no-sandbox', '--disable-setuid-sandbox']
         });

package/dist/services/design-system.d.ts

@@ -1,3 +1,4 @@
+import { type SyncResult } from '../sync/index.js';
 export interface DesignSystemComponent {
     name: string;
     description: string;
@@ -19,10 +20,51 @@ export interface ComponentExample {
     code: string;
     description: string;
 }
+export interface SyncConfig {
+    /** 서버 시작 시 자동 동기화 여부 (기본값: true) */
+    autoSync?: boolean;
+    /** 동기화 상세 로그 출력 여부 */
+    verbose?: boolean;
+}
 export declare class DesignSystemService {
     private reactComponents;
     private vueComponents;
-    constructor();
+    private syncService;
+    private syncConfig;
+    private initialized;
+    private lastSyncResult;
+    constructor(syncConfig?: SyncConfig);
+    /**
+     * 서비스 초기화 (비동기)
+     * 서버 시작 시 호출하여 GitHub에서 최신 컴포넌트 동기화
+     */
+    initialize(): Promise<void>;
+    /**
+     * 수동 동기화 실행
+     */
+    syncComponents(force?: boolean): Promise<SyncResult>;
+    /**
+     * 마지막 동기화 결과 조회
+     */
+    getLastSyncResult(): SyncResult | null;
+    /**
+     * 캐시 상태 조회
+     */
+    getCacheStatus(): Promise<{
+        exists: boolean;
+        isValid: boolean;
+        metadata: {
+            version: string;
+            lastSyncedAt: string;
+            commitSha: string;
+            reactComponentCount: number;
+            vueComponentCount: number;
+        } | null;
+    }>;
+    /**
+     * 캐시 삭제
+     */
+    clearCache(): Promise<void>;
     /**
      * 디자인 시스템(React, Vue) 컴포넌트 메타데이터 제공 필요.
      * 1. 메타데이터 구조 정의